> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a WhatsApp connection > Registers your own AiSensy or Interakt account. The response includes a `webhook_url` — paste it into your provider dashboard, and set `webhook_secret` there to the same value you sent here, or delivery-status webhooks will fail signature verification. ## OpenAPI ````yaml /openapi.json post /messaging/connections openapi: 3.1.0 info: title: Vocobase API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update account configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. - name: Campaigns description: Batch outbound calling. - name: Billing description: Balance, transactions, and usage summaries. - name: Custom Functions description: HTTP endpoints the agent can call mid-conversation. - name: Extraction Sets description: Reusable sets of post-call extraction fields. - name: Lifecycle Hooks description: Automatic pre-call and post-call integration steps. - name: Messaging description: Bring-your-own WhatsApp sending. - name: Integration Logs description: Audit trail for integration calls. - name: Connectors description: Catalog of tools an agent can be connected to. - name: Customers description: B2B2B sub-tenants and their tool connections. - name: Agent Tools description: Binding connectors and connections to an agent. paths: /messaging/connections: post: tags: - Messaging summary: Create a WhatsApp connection description: >- Registers your own AiSensy or Interakt account. The response includes a `webhook_url` — paste it into your provider dashboard, and set `webhook_secret` there to the same value you sent here, or delivery-status webhooks will fail signature verification. operationId: createMessagingConnection requestBody: required: true content: application/json: schema: type: object required: - provider - name properties: provider: type: string enum: - aisensy - interakt api_mode: type: string enum: - campaign - project description: Required for AiSensy. name: type: string api_key: type: string description: AiSensy, Campaign mode. project_id: type: string description: AiSensy, Project mode. app_password: type: string description: AiSensy, Project mode. secret_key: type: string description: Interakt. webhook_secret: type: string description: >- You choose this value and set the same one in your provider dashboard. Vocobase never generates it. example: provider: aisensy api_mode: campaign name: AiSensy — Sales api_key: sk_live_... webhook_secret: a-secret-you-choose responses: '201': description: Connection created. content: application/json: schema: type: object properties: success: type: boolean const: true data: type: object properties: connection: $ref: '#/components/schemas/MessagingConnection' webhook_secret_note: type: string example: success: true data: connection: id: mc_4d5e6f70-8192-a3b4-c5d6-e7f809122334 connection_id: mc_4d5e6f70-8192-a3b4-c5d6-e7f809122334 provider: aisensy api_mode: campaign channel: whatsapp name: AiSensy — Sales status: ACTIVE is_default: true credentials: api_key: sk_l****9f2c webhook_url: >- https://api.vocobase.com/api/whatsapp/webhooks/aisensy/7c1f9a2b4d6e8013 webhook_secret_set: true last_verified_at: '2026-08-22T10:05:00.000Z' last_error_message: null created_at: '2026-08-22T09:58:00.000Z' updated_at: '2026-08-22T10:05:00.000Z' webhook_secret_note: >- Set this webhook_secret as the signing secret in your provider dashboard so inbound delivery-status webhooks verify. '400': description: >- `provider` or `api_mode` invalid, or the credentials for that provider are missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: 'provider must be one of: aisensy, interakt' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError' components: schemas: MessagingConnection: type: object properties: id: type: string format: uuid connection_id: type: string format: uuid description: Same value as `id`. provider: type: string enum: - aisensy - interakt api_mode: type: string enum: - campaign - project nullable: true description: AiSensy only. Decides which credentials and which send fields apply. channel: type: string enum: - whatsapp name: type: string status: type: string description: '`ACTIVE` once verified.' is_default: type: boolean credentials: type: object additionalProperties: true description: Masked. Secrets are encrypted at rest and never returned in full. webhook_url: type: string format: uri description: >- Paste this into your provider dashboard to receive delivery-status webhooks. webhook_secret_set: type: boolean description: >- Whether a signing secret is stored. The secret itself is never returned. last_verified_at: type: string format: date-time nullable: true last_error_message: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key RateLimitExceeded: description: Per-account rate limit exceeded. Retry after a short backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RATE_LIMITED message: Rate limit exceeded. Retry after 60 seconds. InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ````