Core Concepts

Senders and sessions

Create connected numbers, scan QR codes, check health, and understand sender states.

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.

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.

GET/api/senders

List senders assigned to the API key. Use this to copy the correct `sender_id` into your backend configuration.

Parameter	Type	Description
`x-api-key`required	header	Customer API key created in the dashboard.

200 response

json

[
  {
    "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"
  }
]

GET/api/senders/{sender_id}/status

Check whether an assigned sender is connected before sending.

Parameter	Type	Description
`x-api-key`required	header	Customer API key with access to this sender.

200 response

json

{
  "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.

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.

Need help?

Use Book Integration Help if you want setup help for OTP or automated customer messaging.

Next steps

Quickstart

A practical path from empty workspace to a working server-side integration.

Authentication and access

HookMessage separates customer API keys, dashboard sessions, and internal platform access.

Workspaces

A workspace is the tenant boundary for every customer resource.

Send customer messages

Use `/api/messages/send` for opted-in, application-triggered customer communication.