channels_connect_session_start
🔌 Start connecting a WhatsApp, Telegram or Viber number from your own screen, with no DialogBrain login for the person who owns the number.
Returns {session_id, status, qr, qr_expires_at, expires_at}. qr is the RAW string to draw as a QR code, not a picture. Viber is the exception: its qr is a data:image/png;base64,... URL, the picture of the code Viber itself draws; show it as an image. It is null for the first seconds, while Viber starts. Then poll channels.connect_session.get every 2-3 seconds.
Methods (channels.connect_session.options lists what is supported right now): whatsapp qr or pairing_code; telegram qr or phone; viber qr (scanned in Viber on the phone: More > Settings > Account > Desktop and Tablets). For pairing_code and phone the session starts at need_phone and the number is sent with channels.connect_session.submit.
The account will belong to the user behind the API key. external_ref is your own label (an employee id, a row id): it comes back in get, on the account in channels.list and in the channel.connected webhook.
A workspace with no way to pay for the channel is refused here with error_type billing_required, before any code is shown. Other refusals: permission_denied, unsupported_channel, rate_limited (10 starts per 10 minutes).
Statuses: waiting_scan: show qr (it changes; always draw the one from the latest get; null means the code is not ready yet, keep polling). need_phone: submit the phone number. need_code: submit the code Telegram sent. need_password: submit the Telegram two-step verification password. need_pairing_code: show pairing_code; the person types it in WhatsApp > Linked devices > Link with phone number. connected: account_id, phone, name are set. expired: start a new session. error: error says why.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"channel": "<channel>"
},
"name": "channels_connect_session_start"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | 'qr' (default), 'pairing_code' (whatsapp) or 'phone' (telegram). | |
| channel | Yes | 'whatsapp', 'telegram' or 'viber'. | |
| external_ref | No | Your own label for this connection. Stored with the session and the account. | |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. |