# WhatsApp overview

Bird WhatsApp sends messages through the same platform and the same API keys as [Bird Email](/docs/guides/email/overview) and [Bird SMS](/docs/guides/sms/overview). 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](/docs/guides/whatsapp/templates) 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](/docs/guides/whatsapp/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](/docs/guides/whatsapp/sending-whatsapp).
- **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](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing).

## The WhatsApp app in the dashboard

In the [dashboard](/docs/knowledge-base/getting-started/dashboard-tour), WhatsApp is one of the workspace's channel apps. Its pages:

| Page                                                             | What it's for                                                                                     |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [**Messages**](https://bird.com/dashboard/w/whatsapp/messages)   | Every message you send, with its per-message event timeline and delivery detail                   |
| [**Metrics**](https://bird.com/dashboard/w/whatsapp/metrics)     | Aggregate delivery rate, failure rate, volume, spend, and latency across the workspace            |
| [**Templates**](https://bird.com/dashboard/w/whatsapp/templates) | The pre-approved templates you can send: name, language, category, and a rendered preview of each |
| [**Numbers**](https://bird.com/dashboard/w/whatsapp/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](https://bird.com/dashboard/w/whatsapp/messages) page renders it per message; see [WhatsApp events](/docs/guides/whatsapp/events).
- **Have it pushed**: subscribe a [webhook endpoint](/docs/guides/webhooks) to the `whatsapp.*` event types and react the moment a message moves.
- **Watch the aggregate**: the [Metrics](/docs/guides/whatsapp/tracking-and-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](/docs/guides/whatsapp/sending-whatsapp) | The send API: recipient, template, components, tags, the async model |
| [Templates](/docs/guides/whatsapp/templates)                        | The template catalog, categories and variables, and sending by name  |
| [WhatsApp log](/docs/guides/whatsapp/message-log)                   | Every message, its status, and its event timeline                    |
| [Events](/docs/guides/whatsapp/events)                              | The lifecycle events a message emits, over the API and as webhooks   |
| [WhatsApp metrics](/docs/guides/whatsapp/tracking-and-metrics)      | Aggregate delivery rate, failure rate, and spend numbers             |
| [Rate limits](/docs/guides/rate-limits)                             | Every group's base rate, `whatsapp_send` included, and 429 handling  |