WhatsApp overview
Bird WhatsApp uses the same platform and API keys as Bird Email and Bird SMS. Call the regional host for the API key (https://us1.platform.bird.com or https://eu1.platform.bird.com). WhatsApp endpoints are under /v1/whatsapp/….
Business-initiated sends use a pre-approved message template. Send one from Bird's managed catalog, which needs no number of your own and sends from a Bird-managed sender, or connect a number of your own and send your own templates from it. Contacts can message a number of your own, and Bird records those inbound messages alongside outbound ones.
Rolling out: Connecting your own number is being made available over the coming weeks. When the option appears on the Numbers page of your dashboard, your workspace has it.
How sending works
Send a WhatsApp message with POST /v1/whatsapp/messages: one recipient, one template, and optional tags and metadata. We validate the request and return 202 Accepted with a message ID. Charging and delivery happen asynchronously. The API has no batch endpoint, so send one request per message.
Three ideas shape the whole API:
- Sending and delivery are separate stages. A 202 means Bird accepted the message. The recipient's device receives it only after the message advances through WhatsApp to a terminal delivery result. A read receipt appears as a read_at timestamp and whatsapp.read event; it does not change message status.
- Every business-initiated send uses a template. Supply the template slug, an optional language, and values for its variables. Free-form text and media reach a contact only inside the 24-hour window their own message opens, and only from a number your workspace owns. See Sending WhatsApp messages.
- Category and destination determine sender and price. Each template has an authentication, utility, or marketing category. A managed template sends from the Bird number for its category, so it carries no from field; every other send names its own sender. Price also depends on the recipient's country, and the message is charged in two steps: Bird's fee while Bird processes the send, and Meta's share when the message is delivered. 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 | Inbound and outbound messages, with per-message content, events, and delivery details |
| Metrics | Outbound delivery metrics and inbound message volume |
| Templates | The templates you can send, managed and your own: name, language, category, and a rendered preview |
| Numbers | Bird-managed sender numbers and, once the rollout reaches you, numbers of your own |
Visibility
Bird records a timeline for every message. Outbound timelines include accepted, sent, delivered, read, and failure events. An inbound timeline records when Bird received the message.
- Read a timeline: GET /v1/whatsapp/messages/{message_id}/events returns the message's events. The Messages page shows the same timeline. See WhatsApp events.
- Subscribe to outbound delivery events: send public whatsapp.accepted, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed, and whatsapp.rejected events to a webhook endpoint.
- Review aggregate metrics: the Metrics page has separate Outbound and Inbound tabs.
Receiving
Bird stores inbound messages sent to a number your workspace owns, with a received status. Bird-managed numbers are shared across workspaces, so what contacts send them is not recorded for yours. Find them on the Messages page or with GET /v1/whatsapp/messages?direction=inbound. The message detail shows text, supported media, documents, locations, and content types Bird cannot render. Received media is available for 30 days.
The Inbound tab on the Metrics page shows a Messages received time series and a By phone number breakdown. Bird does not expose whatsapp.received as a public webhook event.
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 slug |
| WhatsApp log | Inbound and outbound messages, content, status, and event timelines |
| Events | Message timelines and public outbound delivery webhooks |
| WhatsApp metrics | Outbound delivery performance and inbound message volume |
| Rate limits | Every group's base rate, whatsapp_send included, and 429 handling |