> ## Documentation Index > Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect a WhatsApp number > Connect a number with a token from your own Meta app (WhatsApp > API Setup): its phone number id, its WhatsApp Business Account id, a permanent access token and the app secret. The number is checked with Meta, and your app is subscribed to its webhooks. The response carries `webhook.url` and a `verify_token`, shown once: enter both in your Meta app under WhatsApp > Configuration and subscribe to the `messages` field. Set `inbound_agent_id` to have an agent answer the number. In the console, Connect WhatsApp opens Meta’s own sign-up instead, with no app of your own needed. Connecting a number you already connected updates it (200). Requires `whatsapp:write`. ## OpenAPI ````yaml /openapi.json post /v1/whatsapp/accounts openapi: 3.1.0 info: title: Wixzel Voice API version: '2026-09-01' description: >- APIs for agentic telephony. One API key, one balance, every voice engine. ## Authentication Send your key as `Authorization: Bearer wv_live_...`. Keys are scoped: grant only what an integration needs. There is no admin scope. ## Versioning The `/v1` prefix covers additive changes. Behavioural changes ship behind a dated `Wixzel-Version` header, and existing keys keep the behaviour they were created with. ## Money Amounts are integer **micro-USD** (1,000,000 = $1.00). Voice usage is billed per second, per token and per character, so a float dollar figure cannot represent it without disagreeing with the ledger. ## Errors Every error carries a stable `code` and a `request_id`. Match on `code`; the `message` is for humans and may change. contact: name: Wixzel Voice url: https://voice.wixzel.com servers: - url: https://api.voice.wixzel.com description: Production security: [] tags: - name: Calls description: Place calls and read what happened on them. - name: Realtime description: Talk to an agent from a browser or app, with no phone line. - name: Agents description: >- The prompt, voice and behaviour of a caller, and its mascot: the animated face people see on your share link, your website and in your apps. - name: Leads description: People to call, and data to merge into prompts. - name: Campaigns description: Call a list of leads with one agent. - name: Knowledge bases description: Facts an agent can draw on mid-call. - name: Phone numbers description: Numbers on your SIP trunks. - name: SIP trunks description: Your carrier connections. - name: Appointments description: Bookings, including ones agents make on calls. - name: Usage description: Itemised billing lines. - name: Billing description: Balance, ledger and top-ups. - name: API keys description: Create, scope and rotate keys. - name: Engines description: What the platform can serve, and what it costs. - name: Voices description: Cloned voices, made from your own recordings, for your agents to speak in. - name: Callers description: Who called your agents, where from and on what, and the blocklist. - name: Webhooks description: Where events are sent, and what happened when they got there. - name: MCP servers description: Other apps’ tools, for agents to use while they are on a call. - name: Tools description: >- Your own tools, for agents to use while they are on a call: a webhook to your server, or an action in the caller’s app. - name: WhatsApp description: >- WhatsApp business numbers, the agents that answer their chats, and messages agents send. - name: Meetings description: >- Agents in Zoom, Google Meet and Teams meetings, through your own Attendee account. paths: /v1/whatsapp/accounts: post: tags: - WhatsApp summary: Connect a WhatsApp number description: >- Connect a number with a token from your own Meta app (WhatsApp > API Setup): its phone number id, its WhatsApp Business Account id, a permanent access token and the app secret. The number is checked with Meta, and your app is subscribed to its webhooks. The response carries `webhook.url` and a `verify_token`, shown once: enter both in your Meta app under WhatsApp > Configuration and subscribe to the `messages` field. Set `inbound_agent_id` to have an agent answer the number. In the console, Connect WhatsApp opens Meta’s own sign-up instead, with no app of your own needed. Connecting a number you already connected updates it (200). Requires `whatsapp:write`. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWhatsAppAccount' responses: '201': description: The connected number, with its webhook settings content: application/json: schema: $ref: '#/components/schemas/CreatedWhatsAppAccount' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The number is connected to another account, or the account limit is reached content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. Retry after the interval in `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: CreateWhatsAppAccount: type: object properties: name: type: string maxLength: 100 access_token: type: string minLength: 20 maxLength: 1000 description: >- A permanent access token from your Meta app (a system user token) with whatsapp_business_messaging and whatsapp_business_management. phone_number_id: type: string pattern: ^\d{5,30}$ waba_id: type: string pattern: ^\d{5,30}$ app_secret: type: string minLength: 16 maxLength: 200 description: >- Your Meta app’s secret, from App settings > Basic. Used only to check that webhooks really come from Meta. inbound_agent_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e required: - access_token - phone_number_id - waba_id - app_secret CreatedWhatsAppAccount: allOf: - $ref: '#/components/schemas/WhatsAppAccount' - type: object properties: verify_token: type: string description: >- Shown once. Enter it with `webhook.url` in your Meta app’s WhatsApp webhook settings, and subscribe to the `messages` field. Empty when the number is in Wixzel Voice’s own Meta app, whose webhook is already set. required: - verify_token Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - insufficient_credits - not_found_error - conflict_error - api_error code: type: string description: Stable machine-readable code. example: agent_not_found message: type: string description: >- Human-readable explanation. Do not match on this — match on code. param: type: string description: Which field caused the failure, when applicable. doc_url: type: string request_id: type: string description: Quote this when asking for help. example: req_01HXYZ... required: - type - code - message - request_id required: - error WhatsAppAccount: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e object: type: string enum: - whatsapp_account name: type: string display_phone_number: type: string example: +91 98765 43210 verified_name: type: string description: The business name WhatsApp shows. phone_number_id: type: string description: Meta’s id for the number. waba_id: type: string description: Meta’s id for the WhatsApp Business Account the number belongs to. quality_rating: type: string description: GREEN, YELLOW, RED or UNKNOWN, as Meta rates the number. example: GREEN messaging_limit_tier: type: - string - 'null' description: How many people the number may start conversations with per day. example: TIER_1K connection: type: string enum: - embedded_signup - manual description: >- `embedded_signup` when connected in the console with Meta’s sign-up; `manual` when connected with your own Meta app’s token. coexistence: type: boolean description: The number also stays on the WhatsApp Business app. status: type: string enum: - connected - error - disconnected last_error: type: - string - 'null' webhook: type: object properties: status: type: string enum: - pending - ok - error description: '`ok` once a webhook from Meta has arrived for this number.' last_received_at: type: - string - 'null' format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' url: type: string format: uri description: >- Where Meta sends this number’s webhooks. For a manual account, set it in your Meta app. required: - status - last_received_at - url inbound_agent_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ description: >- The agent that answers this number’s chats. With none, messages are stored and not answered. example: 6a96a3ead6e886d42462dd3e settings: $ref: '#/components/schemas/WhatsAppAccountSettings' created_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' updated_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' required: - id - object - name - display_phone_number - verified_name - phone_number_id - waba_id - quality_rating - messaging_limit_tier - connection - coexistence - status - last_error - webhook - inbound_agent_id - settings - created_at - updated_at WhatsAppAccountSettings: type: object properties: messaging_enabled: type: boolean description: >- Whether the agent answers messages. Off keeps the number connected for sending only. voice_note_replies: type: boolean description: >- Answer a voice note with a voice note in the agent’s voice, on engines that can (classic and sarvam). Otherwise replies are text. typing_indicator: type: boolean description: Mark messages read and show “typing…” while the agent works. inactivity_minutes: type: integer minimum: 1 maximum: 1440 description: >- A conversation with no message for this long closes; the next message starts a new one. example: 15 offline_reply: type: string maxLength: 1000 description: >- Sent instead of an AI reply when your balance is too low to answer. Empty sends nothing. human_pause_minutes: type: integer minimum: 0 maximum: 1440 description: >- On a number shared with the WhatsApp Business app: after a person replies from the app, the agent waits this long. required: - messaging_enabled - voice_note_replies - typing_indicator - inactivity_minutes - offline_reply - human_pause_minutes securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Wixzel Voice API key: `Authorization: Bearer wv_live_...`. Keys are scoped; grant only what the integration needs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.