Skip to main content
POST
Inicia un flow de conexión de WhatsApp Business desde el CLI. Devuelve una URL del portal donde el usuario completa el embedded signup.
There are two modes to connect a WhatsApp channel:
  • mode: "embedded_signup" (default) — Meta’s official flow for WhatsApp Business Cloud API. Requires a human to complete the Embedded Signup in a browser. This is what keebai whatsapp connect does.
  • mode: "qr" — multi-device QR pairing (no browser, no official WABA). The endpoint starts a session and returns an SSE stream_url; the client receives the QR, scans it with WhatsApp mobile, and when done receives the connected event with the channel_id. This is what keebai whatsapp connect --qr does. Documented in detail at POST /v1/channels/whatsapp/connect (QR mode).

General flow

1

Your backend starts the session

POST /v1/channels/whatsapp/connect. Returns session_id + verification_uri.
2

Show the URL to the user

The user opens it in a browser, logs into the Keebai portal (if not already), and starts Meta’s embedded signup.
3

Poll status every 5 seconds

GET /v1/channels/whatsapp/connect/:session_id until status: completed. The session expires in 15 minutes.
4

Receive the created channel

The polling response with status: completed includes channel: { id, phone_number, ... }.

Start a session

POST /v1/channels/whatsapp/connect Required scope: channels:connect

Request

Response 201

Poll status

GET /v1/channels/whatsapp/connect/:session_id Required scope: channels:connect

Request

Response 200

While the user hasn’t completed signup:
When embedded signup finishes successfully:
Terminal states:

CLI equivalent

The CLI does exactly this flow: creates the session, opens the URL in your browser, polls status, and on completion prints Connected channel ch_xxx (phone_number_id: ...).

Operational notes

Cannot run 100% backend

Meta requires human browser interaction for embedded signup. Your UI needs a visible step for the user.

Subscribe to `whatsapp.channel.connected`

If you’d rather not poll, subscribe to the webhook. Your endpoint receives the event when the channel completes, no polling needed.

Coexistence with WABA Mobile App

If the number is already active in the traditional Business app, set coexistence_enabled: true. Meta syncs the history; the portal reflects it when activating.

The PAT determines the destination company

The channel is attached to the company of the PAT that started the session. There’s no way to create the channel in a different company from the API.

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Body

application/json
mode
enum<string>
default:embedded_signup

Modo de conexión: embedded_signup (default) abre el flujo de Meta en el portal; qr devuelve un stream SSE para escanear desde la terminal con WhatsApp multi-dispositivo.

Available options:
embedded_signup,
qr
pipeline_id
string

Si se especifica, el canal recién creado se asocia automáticamente al pipeline. Sólo aplica al modo embedded_signup.

coexistence_enabled
boolean

Activa el modo coexistencia (si el cliente ya tiene la app de WhatsApp Business activa). Sólo aplica al modo embedded_signup.

name
string

Etiqueta visible del canal cuando se conecta por QR. Default: "WhatsApp QR".

Response

201 - application/json
session_id
string
required
provider
string
required

whatsapp | whatsapp_qr

mode
string
required

embedded_signup | qr

expires_in
number
required

Segundos hasta que la sesión expira

poll_interval
number
required

Segundos sugeridos entre polls

verification_uri
string

URL del portal donde el usuario completa el Embedded Signup

stream_url
string

Ruta del stream SSE de pairing, sólo en modo qr