--- title: "WhatsApp overview" description: "How Bird WhatsApp works: send templates from a Bird-managed or your own number, receive messages, track delivery, and find each guide." canonical: "https://bird.com/docs/guides/whatsapp/overview" --- # WhatsApp overview Bird WhatsApp uses the same platform and API keys as [Bird Email](/docs/guides/email/overview) and [Bird SMS](/docs/guides/sms/overview). 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](/docs/guides/whatsapp/templates). 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](/docs/guides/whatsapp/numbers/connect) and send your own templates from it. Contacts can message a number of your own, and Bird records those inbound messages alongside outbound ones. ## 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. A service message, meaning free-form text or media, reaches a contact only inside the 24-hour window their own message opens, and only from a number your workspace owns. See [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp). - **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](/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) | Inbound and outbound messages, with per-message content, events, and delivery details | | [**Metrics**](https://bird.com/dashboard/w/whatsapp/metrics) | Outbound delivery metrics and inbound message volume | | [**Templates**](https://bird.com/dashboard/w/whatsapp/templates) | The templates you can send, managed and your own: name, language, category, and a rendered preview | | [**Numbers**](https://bird.com/dashboard/w/whatsapp/numbers) | Bird-managed sender numbers and connected numbers of your own | | [**Groups**](https://bird.com/dashboard/w/whatsapp/groups) | WhatsApp groups your business numbers administer, with their participants and invite links | ## 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](https://bird.com/dashboard/w/whatsapp/messages) page shows the same timeline. See [WhatsApp events](/docs/guides/whatsapp/events/message-status). - **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](/docs/guides/webhooks). - **Review aggregate metrics**: the [Metrics](/docs/guides/whatsapp/tracking-and-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 do not receive messages for your workspace. Find messages on the [Messages](https://bird.com/dashboard/w/whatsapp/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](https://bird.com/dashboard/w/whatsapp/metrics/inbound) page shows a **Messages received** time series and a **By phone number** breakdown. To act on each inbound message as it arrives, subscribe to the `whatsapp.received` webhook event instead; see [Inbound message webhooks](/docs/guides/whatsapp/webhooks/messages). Some recipients ask you to stop, and a reply of `STOP` is the commonest way they do it: Bird ships the keyword list, so that works on your numbers with no setup. You can also record a suppression scoped to one business account, or an opt-out covering the whole workspace. Bird blocks later sends to the address either way. See [Opt-outs and keywords](/docs/guides/whatsapp/opt-outs). ## Next steps - [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp): send a template or service message through the API - [Connecting your own number](/docs/guides/whatsapp/numbers/connect): set up a number to send and receive messages under your brand - [Templates](/docs/guides/whatsapp/templates): browse templates and find the variables needed to send them - [Receiving WhatsApp messages](/docs/guides/whatsapp/receiving-whatsapp): read inbound messages and fetch media - [Webhooks](/docs/guides/whatsapp/webhooks): subscribe to incoming messages and delivery updates ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/whatsapp-api) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)