Senders and sessions
Create connected numbers, scan QR codes, check health, and understand sender states.
Who needs this guide
Use this guide only when a paid plan allows your workspace to connect a customer-owned WhatsApp number.
Free Sandbox uses a managed HookMessage sender. Free Sandbox users should return to the quickstart and omit `sender_id`.
Free Sandbox does not connect a number
Do not create a placeholder sender or copy another workspace’s sender ID. Managed Sandbox routing is selected by the backend.
Sender lifecycle
A sender starts as a dashboard-created number, then enters a QR connection flow. After the QR is scanned, the sender becomes connected and can queue messages.
Operators should watch sender status and daily usage before diagnosing application issues. Most failed sends are caused by invalid input, limits, disconnected senders, or missing sender assignment.
- pending_qr: waiting for a QR code.
- qr_ready: QR code is available for scanning.
- connected: ready for message delivery.
- disconnected: the socket is not active; wait for reconnect or reconnect from the dashboard.
- logged_out: the WhatsApp session must be reconnected.
- disabled: intentionally paused by an operator.
Create and connect
Create and reconnect senders from the dashboard so the QR flow, plan limits, audit logs, and workspace permissions are enforced by the customer portal.
Server-side integrations should list assigned senders and check status before sending. They should not try to create senders from browser code or expose service credentials.
- Open Dashboard > WhatsApp Numbers and choose Add number.
- Enter the full international number and a clear display name.
- Scan the newest QR from WhatsApp > Linked Devices.
- Wait until the dashboard status is `connected`.
- Open Dashboard > API Keys and assign the sender to the intended key.
- Copy the returned `sender_id` into server-only configuration.
/api/sendersList senders assigned to the API key. Use this to copy the correct `sender_id` into your backend configuration.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | Customer API key created in the dashboard. |
[
{
"sender_id": "9f4b5d4c-0000-4000-9000-123456789abc",
"workspace_id": "f2aa1d49-9f4b-4f37-9918-d8d8f13fb530",
"phone_number": "212612345678",
"display_name": "Main support",
"status": "connected",
"trust_tier": "trusted",
"daily_limit": 500,
"messages_sent_today": 12,
"is_active": true,
"connected_at": "2026-06-29T16:00:00.000Z",
"created_at": "2026-06-29T15:50:00.000Z"
}
]/api/senders/{sender_id}/statusCheck whether an assigned sender is connected before sending.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | Customer API key with access to this sender. |
{
"sender_id": "9f4b5d4c-0000-4000-9000-123456789abc",
"workspace_id": "f2aa1d49-9f4b-4f37-9918-d8d8f13fb530",
"phone_number": "212612345678",
"status": "connected",
"connected_at": "2026-06-29T16:00:00.000Z"
}QR and session troubleshooting
QR codes are short-lived. If the dashboard shows an expired or stale QR, refresh the sender connection and scan the newest QR from WhatsApp Linked Devices.
A sender in `logged_out` or `disabled` state cannot send. Re-enable or reconnect it from the dashboard before retrying API requests.
- QR does not appear: wait for `qr_ready`, refresh the sender panel, then retry the connect action.
- QR scan fails: confirm the phone has internet access and scan from WhatsApp Linked Devices, not the camera app.
- Status stays pending_qr: scan a fresh QR; old QR images expire quickly.
- Status becomes disconnected: wait for automatic reconnect, then check `/api/senders/{sender_id}/status`.
- Status becomes logged_out: the WhatsApp device was unlinked; connect the sender again.
- sender_session_owned_elsewhere: only one service instance should own the same sender socket at a time.
Phone number format
Sender and receiver phone numbers are normalized before storage and sending. The API removes spaces, dashes, parentheses, and a leading `00` international prefix.
Do not send local numbers that start with `0`. Include the country code and omit the plus sign in stored examples.
- Accepted: `+212 612-345-678` becomes `212612345678`.
- Accepted: `00212612345678` becomes `212612345678`.
- Accepted: `212612345678` stays `212612345678`.
- Rejected: `0612345678` because the country code is missing.
- Rejected: numbers shorter than 6 digits or longer than 15 digits.
Need help?
Use Book Integration Help if you want setup help for OTP or automated customer messaging.
Continue building
Next steps
API keys and sender assignment
API clients are workspace-scoped credentials with explicit sender permissions.
Send customer messages
Use `/api/messages/send` for opted-in, application-triggered customer communication.
Send OTP
Use OTP for login, signup, order verification, and customer confirmation flows.
Troubleshooting
Use this page when a new integration does not send, status stays queued, or webhook verification fails.