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 abre el flujo de Meta en el portal.
embedded_signup Si se especifica, el canal recién creado se asocia automáticamente al pipeline.
Activa el modo coexistencia (si el cliente ya tiene la app de WhatsApp Business activa).
Etiqueta visible del canal cuando se conecta por QR. Default: "WhatsApp QR".
Response
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