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, and messages go out from Bird-managed numbers; connecting your own number and authoring your own templates are not available yet (see Phone number setup).
How sending works
You send a WhatsApp message with POST /v1/whatsapp/messages: one recipient, one template, plus optional tags and metadata. Bird validates the request and returns 202 Accepted with a message ID; the charge and delivery happen asynchronously from there. 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. 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 the message is charged when Bird processes the send, priced on the category together with the recipient's country; see Cost and billing.
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 |
| Metrics | Aggregate delivery rate, failure rate, volume, spend, and latency across the workspace |
| Templates | The pre-approved templates you can send: name, language, category, and a rendered preview of each |
| Numbers | The Bird-managed WhatsApp sender numbers available to your workspace |
Visibility
Every message emits an event timeline: accepted, sent, delivered, read, or a failure. You can consume it three ways:
- Pull it: GET /v1/whatsapp/messages/{message_id}/events returns the timeline, and the Messages page renders it per message; see WhatsApp events.
- Have it pushed: subscribe a webhook endpoint to the whatsapp.* event types and react the moment a message moves.
- Watch the aggregate: the Metrics page tracks delivery rate, failure causes, and spend across everything you send.
Receiving
Inbound WhatsApp messages are not available yet; the channel is outbound-only today.
Next steps
| Page | What it covers |
|---|---|
| Sending WhatsApp messages | The send API: recipient, template, components, tags, the async model |
| Templates | The template catalog, categories and variables, and sending by name |
| WhatsApp log | Every message, its status, and its event timeline |
| Events | The lifecycle events a message emits, over the API and as webhooks |
| WhatsApp metrics | Aggregate delivery rate, failure rate, and spend numbers |
| Rate limits | Every group's base rate, whatsapp_send included, and 429 handling |