> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# WhatsApp integration

A **WhatsApp integration** connects a workspace to a WhatsApp Business number. Once connected, messages sent to that number are answered by the workspace's assistant. A workspace has at most one WhatsApp integration.

> **Warning**
>
> WhatsApp is **messaging only**. The assistant replies to text messages (and interactive button replies); it does **not** answer WhatsApp voice or video calls — a call placed to the number reaches no assistant. For a phone assistant, use the [voice integration](/documentation/core-concepts/voice-integration), which uses a dedicated phone number.

## What the API exposes

`GET /v1/workspaces/{workspaceId}/integrations/whatsapp` returns a redacted status:

| Field               | Meaning                                                      |
| ------------------- | ------------------------------------------------------------ |
| `connected`         | Whether WhatsApp is set up. `{ connected: false }` when not. |
| `phoneNumberId`     | The Meta phone number id.                                    |
| `businessAccountId` | The Meta WhatsApp Business Account (WABA) id.                |
| `businessId`        | The Meta business id.                                        |

> **Warning**
>
> The WhatsApp **access token is never returned** by the API — only the non-secret Meta identifiers above.

## Connecting (Embedded Signup)

WhatsApp onboarding uses Meta's Embedded Signup, driven from your own UI so your API key never reaches the end user's browser:

1. **Create a signup URL** — `POST /v1/workspaces/{workspaceId}/integrations/whatsapp/connect-token`. This returns a `connectUrl` with a short-lived, single-use token for that workspace and account.
2. **Render the connect page** — embed the `connectUrl` in an iframe. The user completes Meta's Embedded Signup there, which normally includes **selecting a phone number** and, if prompted, entering its **6-digit two-step verification PIN**.

In the usual flow, the WABA is connected and the chosen number is registered, so the integration is ready. The iframe reports success back to your page.

## Finishing a connection that has no phone number

Embedded Signup can end with the WABA connected but **no usable phone number bound** — for example the user did not select a number, or the number failed to register (the PIN step was skipped, or the wrong PIN was entered).

> **Warning**
>
> Until a phone number is connected and registered, **end users cannot message the assistant** — inbound WhatsApp messages have no registered number to be delivered to, so they never reach the workspace. Connecting the WABA alone is not enough; a bound, registered number is what makes the integration live.

Complete it over the API:

1. **List the numbers on the WABA** — `GET /v1/workspaces/{workspaceId}/integrations/whatsapp/phone-numbers`. Each entry indicates whether it is already `inUse` by another workspace.
2. **Register a number** — `POST /v1/workspaces/{workspaceId}/integrations/whatsapp/register-phone` binds a chosen number to the workspace. If the number is already live on the Cloud API it binds directly; otherwise supply the 6-digit two-step verification PIN, collected in your own UI (if two-step verification was never set up, the PIN you send becomes the new one).

> **Info**
>
> You only need these two endpoints as a fallback. Check the current state any time with `GET /v1/workspaces/{workspaceId}/integrations/whatsapp` — once `connected` is true and `phoneNumberId` is set, the integration is complete and no further steps are needed.

## Disconnecting

`DELETE /v1/workspaces/{workspaceId}/integrations/whatsapp` disconnects WhatsApp from the workspace.