Core concepts

WhatsApp integration

Connect a workspace to WhatsApp Business so it answers WhatsApp messages.

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.

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, which uses a dedicated phone number.

What the API exposes

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

FieldMeaning
connectedWhether WhatsApp is set up. { connected: false } when not.
phoneNumberIdThe Meta phone number id.
businessAccountIdThe Meta WhatsApp Business Account (WABA) id.
businessIdThe Meta business id.

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).

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).

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.