POST /v1/channels/whatsapp/connect (QR mode)

The qr mode of POST /v1/channels/whatsapp/connect pairs a channel without Embedded Signup: the client receives a QR, scans it with WhatsApp mobile (Settings -> Linked Devices -> Link a device) and when pairing completes receives the channel_id of the newly created channel. No browser step, no official WABA, no Cloud API. The integration uses WhatsApp multi-device under the hood. This is what keebai whatsapp connect --qr does in the CLI.

General flow

Your backend starts the session

POST /v1/channels/whatsapp/connect with mode: "qr". Returns session_id + stream_url (relative SSE path).

Subscribe to the SSE stream

GET {stream_url} with Accept: text/event-stream and Authorization: Bearer <PAT>. You’ll receive real-time events: qr, connecting, connected, failed, disconnected.

Show the QR to the user

Each qr event carries a string payload. Render it as a QR (in the terminal with qrcode-terminal, on web with qrcode, etc.). If the code expires before it’s scanned, a new qr arrives automatically.

Receive the created channel

Once scanned successfully, the stream closes with a connected event whose data includes channel_id, phone_number and push_name.

Start a QR 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 '{
    "mode": "qr",
    "name": "WhatsApp Soporte"
  }'

Field	Type	Required	Description
`mode`	`"qr"`	yes	Selects the QR flow.
`name`	string	no	Channel label. Default `"WhatsApp QR"`.

pipeline_id and coexistence_enabled don’t apply to QR mode. If you send them, the API responds 400 QR_MODE_CANNOT_USE_COEXISTENCE_OR_PIPELINE.

Response 201

{
  "session_id": "cs_01HXYZ...",
  "provider": "whatsapp_qr",
  "mode": "qr",
  "stream_url": "/v1/channels/whatsapp/connect/cs_01HXYZ.../qr-stream",
  "expires_in": 300,
  "poll_interval": 5
}

Field	Type	Description
`session_id`	string	QR session id. Use it in the `stream_url` path.
`stream_url`	string	Relative path of the SSE stream (prepend the API host).
`expires_in`	number	Seconds until pairing expires if scanning isn’t completed (5 minutes). The stream emits fresh QRs while the window is open.

SSE event stream

GET /v1/channels/whatsapp/connect/:session_id/qr-stream Required scope: channels:connect Headers: Accept: text/event-stream, Authorization: Bearer kbai_pk_xxx.

Events

Event	When	`data`
`qr`	A QR code is ready to scan. Re-emitted when the code expires and refreshes.	string (QR payload) or `{ "data": "<qr-string>", "expires_at": "<iso>" }`
`connecting`	Mobile scanned the QR; WhatsApp is establishing the session.	empty object or state
`connected`	Pairing complete, channel created.	`{ "channel_id": "ch_...", "phone_number": "+56...", "push_name": "Juan" }`
`failed`	Pairing error (timeout, invalid code, linked-device limit, etc.).	`{ "reason": "<description>" }`
`disconnected`	The device was unlinked during pairing.	`{ "reason": "<description>" }`

When connected, failed or disconnected arrives, the stream closes. The client should close the connection too.

curl example

curl -N \
  -H "Authorization: Bearer kbai_pk_xxx" \
  -H "Accept: text/event-stream" \
  https://api.keebai.com/v1/channels/whatsapp/connect/cs_01HXYZ.../qr-stream

event: qr
data: 2@AbcDe…/long-string

event: qr
data: 2@FghIj…/refresh

event: connecting
data: {}

event: connected
data: {"channel_id":"ch_01HXYZ...","phone_number":"+56987654321","push_name":"Juan"}

Rendering the QR

In a terminal with qrcode-terminal (Node):

import qrcode from "qrcode-terminal";
qrcode.generate(payload, { small: true });

On the web, with qrcode:

import QRCode from "qrcode";
QRCode.toCanvas(canvasEl, payload);

CLI equivalent

keebai whatsapp connect --qr [--name "WhatsApp Soporte"]

The CLI creates the session, opens the stream, draws the QR in the terminal, refreshes it automatically, and on scan prints Channel ch_xxx connected (phone +56…, as Juan).

Troubleshooting

Expired QR

Pairing emits fresh QRs automatically every ~20 seconds. Don’t restart the session: just wait for the next qr event.

4 linked-device limit

WhatsApp allows up to 4 devices per account. If the session ends with failed mentioning device limit, free a slot on the mobile (Settings -> Linked Devices) and call POST /v1/channels/whatsapp/connect again.

Expired session (5 min)

If nobody scanned, the stream closes and the session_id stops working. Request a new session.

Don't use Cloud API against this channel

QR channels don’t support templates or bulk sends (Meta doesn’t expose Cloud API on multi-device). A template message on channel: "whatsapp_qr" is rejected with 422 MESSAGE_TYPE_NOT_SUPPORTED_FOR_CHANNEL, and POST /v1/messages/bulk returns 400 QR_NOT_SUPPORTED_FOR_TEMPLATE_OR_BULK. Text and media work as usual.

Sending messages

Once connected, QR channels show up in GET /v1/whatsapp/numbers with connection_type: "qr" and are used with the same endpoint as Cloud API ones:

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_qr",
    "channel_id": "665f1a2b3c4d5e6f70819234",
    "to": "+5491155555555",
    "message": { "type": "text", "body": "Hello from the QR channel" }
  }'

Get started

Contacts

WhatsApp

WhatsApp Flows

Templates

Channels

POST /v1/channels/whatsapp/connect (QR mode)

General flow

Start a QR session

Request

Response 201

SSE event stream

Events

curl example

Rendering the QR

CLI equivalent

Troubleshooting

Expired QR

4 linked-device limit

Expired session (5 min)

Don't use Cloud API against this channel

Sending messages

​General flow

​Start a QR session

​Request

​Response 201

​SSE event stream

​Events

​curl example

​Rendering the QR

​CLI equivalent

​Troubleshooting

Expired QR

4 linked-device limit

Expired session (5 min)

Don't use Cloud API against this channel

​Sending messages

General flow

Start a QR session

Request

Response 201

SSE event stream

Events

curl example

Rendering the QR

CLI equivalent

Troubleshooting

Sending messages