Skip to main content
POST
/
v1
/
channels
/
whatsapp
/
connect
Inicia un flow de conexión de WhatsApp Business desde el CLI. Devuelve una URL del portal donde el usuario completa el embedded signup.
curl --request POST \
  --url https://api.keebai.com/v1/channels/whatsapp/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mode": "embedded_signup",
  "pipeline_id": "<string>",
  "coexistence_enabled": true,
  "name": "<string>"
}
'
{}
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

curl -X POST https://api.keebai.com/v1/channels/whatsapp/connect \
  -H "Authorization: Bearer kbai_pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "pip_01HXYZ...",
    "coexistence_enabled": false
  }'
FieldTypeRequiredDescription
mode"embedded_signup" | "qr"noDefault embedded_signup. When set to qr, the rest of the fields change — see QR mode.
pipeline_idstringno(embedded_signup only) Id of the pipeline to attach the new channel to. If omitted, the portal uses the default pipeline.
coexistence_enabledbooleanno(embedded_signup only) true if the number is already registered in the traditional WhatsApp Business App and you want coexistence with Cloud API. Default false.
namestringno(qr only) Label for the QR channel. Default "WhatsApp QR".

​
Response 201

{
  "session_id": "cs_01HXYZ...",
  "verification_uri": "https://app.keebai.com/connect/whatsapp?session=cs_01HXYZ...",
  "expires_in": 900,
  "poll_interval": 5
}
FieldTypeDescription
session_idstringSession id. Use it to poll status.
verification_uristringPortal URL the user must open. Auto-triggers the embedded signup modal.
expires_innumberSeconds until the session expires (15 minutes).
poll_intervalnumberSuggested seconds between polls.

​
Poll status

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

​
Request

curl https://api.keebai.com/v1/channels/whatsapp/connect/cs_01HXYZ \
  -H "Authorization: Bearer kbai_pk_xxx"

​
Response 200

While the user hasn’t completed signup: 
{
  "status": "pending"
}
When embedded signup finishes successfully: 
{
  "status": "completed",
  "channel": {
    "id": "ch_01HXYZ...",
    "name": "Soporte Chile",
    "type": "whatsapp",
    "is_active": true,
    "phone_number": "+56987654321",
    "phone_number_id": "1234567890",
    "business_account_id": "9876543210"
  }
}
Terminal states:
StatusMeaning
completedChannel created. It started receiving Meta webhooks immediately.
expired15 minutes elapsed without completing. Start a new session.
cancelledThe user cancelled from the portal. Start a new one if you want to retry.

​
CLI equivalent

keebai whatsapp connect [--pipeline pip_01HXYZ] [--coexistence]
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

The response is of type object.