WhatsApp overview
Bird WhatsApp sends messages through the same platform and the same API keys as Bird Email and Bird SMS. You call Bird with a bk_{region}_… key against your regional host (https://us1.platform.bird.com or https://eu1.platform.bird.com); Bird sends the message to WhatsApp, and reports it through to a delivery receipt. One API, one set of credentials, per-channel endpoints under /v1/whatsapp/….
Business-initiated WhatsApp is template-only: every send names a pre-approved message template and supplies its variables. There is no free-text send yet.
Billing — Bird charges for a WhatsApp message when it is sent, regardless of whether it is ultimately delivered. The price depends on the destination country and the template's category; see WhatsApp pricing.
The WhatsApp app in the dashboard
In the dashboard, WhatsApp is one of the workspace's channel apps. Its pages:
| Page | What it's for |
|---|---|
| Messages | Every message you send, with its per-message event timeline and delivery detail |
| Templates | The pre-approved templates you can send — name, language, category, and a rendered preview of each |
| Numbers | The WhatsApp sender numbers available to your workspace |
How sending works
You send a WhatsApp message with POST /v1/whatsapp/messages: one recipient, one template. Bird validates the request and returns 202 Accepted with a message ID; pricing, the charge, and delivery all happen asynchronously from there. A 202 means Bird has durably accepted your send and is working on it; the actual outcome (sent to WhatsApp, delivered, read, or failed) arrives afterwards through events, webhooks, and the message read endpoints. Unlike SMS and email, there is no batch endpoint — send one call per message.
Three ideas shape the whole API:
- A send is not a delivery. The 202 means Bird accepted the message, not that a phone received it. Each message walks its own lifecycle — accepted, sent to WhatsApp, then a terminal receipt — and the receipt can arrive seconds or minutes later. A read receipt is reported separately as a read_at timestamp and a whatsapp.read event, not as a status.
- Every send uses a template (for now). Business-initiated WhatsApp currently requires a pre-approved template; other message types will follow. You supply the template's name, its language, and text values for any {{n}} variables it declares — see Sending WhatsApp messages.
- Category and destination drive sender and price. Each template carries a category — authentication, utility, or marketing. Bird selects the sender number from that category (there is no from field), and pricing is keyed on the category together with the recipient's country — see WhatsApp pricing.
Sending
Sending WhatsApp messages covers the send API in depth: the recipient, the template name and language, filling template variables through components, the async 202 model, what isn't supported yet, and idempotent retries.
Visibility
Every message produces an event timeline — accepted, sent, delivered, read, or a failure:
- Messages — the per-message view in the dashboard: every send, its event timeline, and the template that produced it.
- Events — the per-message lifecycle stream behind the log.
Events
Every WhatsApp message emits events as it moves through its lifecycle — accepted, sent to WhatsApp, delivered, read, or a failure. Read a message's events with GET /v1/whatsapp/messages/{message_id}/events; see WhatsApp events for the full event list and payload. Receiving them on your own endpoint through webhooks is coming soon.
Receiving
Inbound messages are coming soon.
Next steps
| Page | What it covers |
|---|---|
| Sending WhatsApp messages | The send API — recipient, template, components, the async model, retries |
| Templates | The template catalogue, categories and variables, and sending by name |
| Messages | Every message, its status, and its event timeline |
| Events | The lifecycle events a message emits, and reading them from the API |
| Tracking & metrics | Aggregate delivery and spend numbers (coming soon) |