---
title: "WhatsApp templates"
description: "Browse the WhatsApp templates a workspace can send, inspect each one's category, languages, and variables, then send it by slug."
canonical: "https://bird.com/docs/guides/whatsapp/templates"
---

# WhatsApp templates

Business-initiated WhatsApp sends use a pre-approved **template**. A template contains fixed text and variables, so a send supplies only values such as an OTP code or order number.

Bird ships a managed catalog, registers its contents with WhatsApp, and sends it from Bird's own numbers; its slugs begin with `bird_`. A workspace that has connected a [number of its own](/docs/guides/whatsapp/numbers/connect) can also author templates on its own WhatsApp Business Account. The [Templates](https://bird.com/dashboard/w/whatsapp/templates) page shows every template the workspace can send and how each one renders.

![The WhatsApp Templates page in the Bird dashboard, showing the template list. A search box with status and category filters sits above the table. Each row shows one template's status, which is Draft or Active, then its name and slug, its category, its stocked languages, the WABA holding it, and when it last changed.](/images/docs/dashboard-whatsapp-templates.png)

## Browsing templates in the dashboard

Open [**Templates**](https://bird.com/dashboard/w/whatsapp/templates) at **WhatsApp** > **Templates**. **Your templates** holds the templates this workspace authored; **All templates** adds the Bird-managed catalog. Search by name or filter by status and category, and switch between the card grid and the list view with the toggle beside the filters.

In list view, each row shows the fields you need to pick and send a template:

- **Status**: whether the template is sendable overall. Managed catalog templates report `active`; a template of your own reports where its own approval stands. Check the language list to confirm that the required language is available.
- **Name**: the display label, with the template's `slug` beneath it. Send with the `slug`.
- **Languages**: the languages the template is registered in, such as English and Dutch.
- **Category**: `authentication`, `utility`, or `marketing`. The category governs how WhatsApp treats the message, which Bird number a managed template sends from, and, with the destination country, the [price](https://bird.com/pricing/whatsapp).
- **WABA**: **Bird-managed** for catalog templates. A template of your own shows the WhatsApp Business Account holding it, and sends only from a number on that same account.
- **Updated**: when the template last changed.

Click a row to open the template's detail.

## What's in a template

The detail view renders the message body, variables, and buttons in a WhatsApp-style preview.

The detail also provides a **cURL** example for [`POST /v1/whatsapp/messages`](/docs/guides/whatsapp/sending-whatsapp), using the regional host and the template's example values. Replace the API key, recipient, and variable values before sending.

The example is the fastest way to see the shape a send has to match. Over the API, the same content comes from the template's version ([Reading a template's content](#reading-a-templates-content)).

## Listing templates from the API

`GET /v1/whatsapp/templates` returns a cursor-paginated catalog. The request requires `whatsapp_management` read access. Use HTTP or an [SDK](/docs/sdks) raw-request method.

**TypeScript**

```typescript
type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});
```

Examples: [TypeScript](/docs/guides/whatsapp/templates.ts.md) · [Python](/docs/guides/whatsapp/templates.py.md) · [Go](/docs/guides/whatsapp/templates.go.md) · [PHP](/docs/guides/whatsapp/templates.php.md) · [cURL](/docs/guides/whatsapp/templates.curl.md)

Each entry identifies the template, its category, and its available languages. Read the live version separately for message content.

```json
{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}
```

The example response abbreviates the `bird_otp` language lists.

The fields a send depends on:

- **`slug`**: the handle used in a send. Managed template slugs begin with `bird_`, a prefix reserved for them.
- **`waba`**: the WhatsApp Business Account holding the template's languages at Meta, and the account a sender number has to belong to. Absent on a managed template because Bird manages its account.
- **`available_languages`**: languages that can be sent. A paused, disabled, archived, or limited language leaves this list.
- **`on_missing_language`**: what happens when the requested language is unavailable. Bird-managed WhatsApp templates use `fail`, which rejects the send rather than substituting another language.

### Status and language status

Bird-managed templates report `status: active`. `languages.<tag>.status` reports WhatsApp's state for one language, such as `approved`, `paused`, or `disabled`.

An active template can still have an unavailable language. Use `available_languages` to decide whether a language is sendable.

### Reading a template's content

Message content belongs to a language in the live version. Read `live_version_id` from the template, then request the required language:

**TypeScript**

```typescript
const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});
```

Examples: [TypeScript](/docs/guides/whatsapp/templates.ts.md) · [Python](/docs/guides/whatsapp/templates.py.md) · [Go](/docs/guides/whatsapp/templates.go.md) · [PHP](/docs/guides/whatsapp/templates.php.md) · [cURL](/docs/guides/whatsapp/templates.curl.md)

The template reference accepts a `slug` or `wat_` ID. `GET …/versions/{version_id}/languages` lists the version's languages without their content.

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

The send's `components` must match the template. `example_parameters` identifies each placeholder. In this example, the body parameters use `name: "ref"` and `name: "amount"`. A positional template omits `name` and takes values in `{{n}}` order. Parameterized buttons have their own `example_parameters`.

The language `category` is the Meta category used for pricing. It can differ from the template's registered category if Meta reclassifies the language.

The version's `variables` list summarizes every placeholder with its key, type, required flag, and constraint. Named placeholders use their names as keys. Positional placeholders use their number.

## 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:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
  },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/docs/guides/whatsapp/templates.ts.md) · [Python](/docs/guides/whatsapp/templates.py.md) · [Go](/docs/guides/whatsapp/templates.go.md) · [PHP](/docs/guides/whatsapp/templates.php.md) · [CLI](/docs/guides/whatsapp/templates.cli.md) · [MCP](/docs/guides/whatsapp/templates.mcp.md) · [cURL](/docs/guides/whatsapp/templates.curl.md)

## Sending by category

Every template carries one of Meta's three categories, and the category changes what you have to do before a send succeeds as well as what it costs. Authoring or copying an authentication template of your own needs a verified business, but sending one doesn't: Bird's managed `bird_otp` sits on Bird's own WhatsApp Business Account and sends with no verification of yours. Marketing templates always send from a WhatsApp Business Account of your own, over a second Meta API that Bird routes to automatically. Utility templates have the fewest prerequisites of the three.

- [Authentication templates](/docs/guides/whatsapp/templates/authentication): one-time passcodes, the copy-code button, and the verification gate on authoring one
- [Utility templates](/docs/guides/whatsapp/templates/utility): order updates, appointment reminders, and account notices
- [Marketing templates](/docs/guides/whatsapp/templates/marketing): promotional sends, the business account you need, and the opt-out expectation

## Next steps

- [Sending WhatsApp messages](/docs/guides/whatsapp/sending-whatsapp): the full send payload the `template` object slots into
- [WhatsApp template guidelines](/docs/knowledge-base/whatsapp/template-guidelines): the rules Meta reviews a template against
- [Authentication templates](/docs/guides/whatsapp/templates/authentication): one-time passcodes and the business-verification gate on authoring one
- [WhatsApp pricing](https://bird.com/pricing/whatsapp): how category and destination set the price

## 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)