# WhatsApp templates

Business-initiated WhatsApp messages are sent from a **template**: a pre-approved message that WhatsApp has reviewed for its category. A template carries fixed text plus `{{n}}` variables, so a send only supplies the values that change (an OTP code, an order number) and WhatsApp assembles the final message. Today every WhatsApp send names a template; there is no free-text send yet.

Templates are **Bird-managed** today: a catalog of templates Bird has registered with WhatsApp, which you send from rather than authoring your own. The catalog is stocked per region, so the templates you see are the ones available for the region you call. The [Templates](https://bird.com/dashboard/w/whatsapp/templates) page shows what's available and exactly how each one renders.

![The WhatsApp Templates page in the Bird dashboard: a search box with Status and Category filters above a table of approved templates (bird_otp, bird_signin_alert, bird_appointment_reminder, bird_delivery_update), each row showing its Status, Name, an en Language, a Category of authentication or utility, and a Bird-managed WABA](/images/docs/dashboard-whatsapp-templates.png)

## Browsing templates in the dashboard

The [**Templates**](https://bird.com/dashboard/w/whatsapp/templates) tab, under WhatsApp, lists every template available to your workspace. Search by name and filter by status or category to find one.

Each row shows the fields you need to pick and send a template:

- **Status**: the template's WhatsApp review and health state. **Approved** templates passed review and are sendable; `Pending` (review in progress) and `Rejected` (failed review) are the other review outcomes, while `Paused`, `Disabled`, `In appeal`, `Pending deletion`, and `Limit exceeded` track an approved template's ongoing standing with WhatsApp. Every template in Bird's catalog is currently approved.
- **Name**: the template reference (for example `bird_otp`). This is what you pass as `template.name` when sending.
- **Language**: the language the template is registered in (e.g. `en`, `pt_BR`).
- **Category**: `authentication`, `utility`, or `marketing`. The category governs how WhatsApp treats the message, which sender number Bird uses, and, with the destination country, the [price](https://bird.com/pricing/whatsapp).
- **WABA**: the WhatsApp Business Account the template belongs to; Bird-managed templates are marked accordingly.

Click a row to open the template's detail.

## What's in a template

The detail view renders the template the way a recipient sees it: a WhatsApp-style message bubble with the body text, any `{{n}}` variables highlighted, and the template's buttons, so you can confirm the wording and layout before you send.

Alongside the preview is a ready-to-run **cURL example**: a complete [`POST /v1/whatsapp/messages`](/docs/guides/whatsapp/sending-whatsapp) call for that template, pointed at your region's host, with a `components` array pre-filled with the template's example values. Copy it, swap in your API key and real values, and send.

## Listing templates from the API

`GET /v1/whatsapp/templates` returns the catalog in full (the list is not paginated). Reading templates needs an API key with the `whatsapp_management` scope:

```bash
curl https://us1.platform.bird.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $BIRD_API_KEY"
```

Each entry carries the template's `name` (the reference you send by), `language`, `category`, `status`, its `scope` (`system` for a built-in Bird template), and its `components` with example values for every placeholder. Read a template's components to know which parameters a send must supply:

```json
{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "text": "A1B2C3D4", "type": "text" },
        { "text": "EUR 49.99", "type": "text" }
      ],
      "text": "Your order {{1}} has been confirmed for a total of {{2}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "name": "bird_order_confirmation",
  "scope": "system",
  "status": "approved"
}
```

## Sending with a template

Name the template in the send's `template` object and fill its variables through `components`; see [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp) for the full payload:

```bash
curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "name": "bird_otp",
      "language": "en",
      "components": [
        { "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
        { "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
      ]
    }
  }'
```

## Next steps

- [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp): the full send payload the `template` object slots into
- [WhatsApp log](/docs/guides/whatsapp/message-log): find a sent message and follow its lifecycle
- [WhatsApp pricing](https://bird.com/pricing/whatsapp): how category and destination set the price