POST /v1/channels/whatsapp/connect
Kick off the connection flow for a new WhatsApp Business channel from your CLI or backend, without going through the portal.
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 whatkeebai whatsapp connectdoes.mode: "qr"— multi-device QR pairing (no browser, no official WABA). The endpoint starts a session and returns an SSEstream_url; the client receives the QR, scans it with WhatsApp mobile, and when done receives theconnectedevent with thechannel_id. This is whatkeebai whatsapp connect --qrdoes. Documented in detail at POST /v1/channels/whatsapp/connect (QR mode).
General flow
Your backend starts the session
POST /v1/channels/whatsapp/connect. Returns session_id + verification_uri.Show the URL to the user
Poll status every 5 seconds
GET /v1/channels/whatsapp/connect/:session_id until status: completed. The session expires in 15 minutes.Receive the created channel
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:CLI equivalent
Connected channel ch_xxx (phone_number_id: ...).
Operational notes
Cannot run 100% backend
Subscribe to `whatsapp.channel.connected`
Coexistence with WABA Mobile App
coexistence_enabled: true. Meta syncs the history; the portal reflects it when activating.The PAT determines the destination company
Authorizations
Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.
Body
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.
embedded_signup, qr Si se especifica, el canal recién creado se asocia automáticamente al pipeline. Sólo aplica al modo embedded_signup.
Activa el modo coexistencia (si el cliente ya tiene la app de WhatsApp Business activa). Sólo aplica al modo embedded_signup.
Etiqueta visible del canal cuando se conecta por QR. Default: "WhatsApp QR".
Response
whatsapp | whatsapp_qr
embedded_signup | qr
Segundos hasta que la sesión expira
Segundos sugeridos entre polls
URL del portal donde el usuario completa el Embedded Signup
Ruta del stream SSE de pairing, sólo en modo qr