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 from Bird's managed catalog. Bird selects a managed sender number from the template category. Contacts can reply, and Bird records their inbound messages alongside outbound messages.
Preview: Connecting your own number through Embedded Signup is available only to eligible workspaces.
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. See Sending WhatsApp messages.
- Category and destination determine sender and price. Each template has an authentication, utility, or marketing category. Bird selects the managed sender for that category. The request has no from field. Price also depends on 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 | Inbound and outbound messages, with per-message content, events, and delivery details |
| Metrics | Outbound delivery metrics and inbound message volume |
| Templates | The pre-approved templates you can send: name, language, category, and a rendered preview of each |
| Numbers | Managed sender numbers and, for eligible workspaces, own numbers connected through the Preview |
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 WhatsApp messages with a received status. 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 |