---
title: "List WhatsApp template events"
canonical: "https://bird.com/docs/api/reference/list-whatsapp-template-events"
---

# List WhatsApp template events

`GET /v1/whatsapp/templates/{template_ref}/events`

Returns the template's history since Bird began recording it, newest
first:

- A status WhatsApp gave one of its languages, such as an approval, a
  rejection, a pause, a reinstatement, or a deletion.
- A change in a language's quality rating.

Use it to see when a language was paused or its quality dropped, rather
than polling
[Get a WhatsApp template](/docs/api/reference/get-whatsapp-template).
Changes Bird makes, such as submitting a language for review or deleting
it at your request, are not listed. A Bird-managed template has no
history and returns an empty page. A template that does not belong to the
workspace, or no longer exists, returns `404`.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

## Code samples

**TypeScript**

```ts
for await (const event of bird.whatsapp.templates.listEvents("order_update", { language: "en-US" })) {
  console.log(event.created_at, event.type, event.summary);
}
```

Examples: [TypeScript](/docs/api/reference/list-whatsapp-template-events.ts.md) · [Python](/docs/api/reference/list-whatsapp-template-events.py.md) · [Go](/docs/api/reference/list-whatsapp-template-events.go.md) · [PHP](/docs/api/reference/list-whatsapp-template-events.php.md) · [CLI](/docs/api/reference/list-whatsapp-template-events.cli.md) · [MCP](/docs/api/reference/list-whatsapp-template-events.mcp.md) · [cURL](/docs/api/reference/list-whatsapp-template-events.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "wte_01krdgeqcxet5s7t44vh8rt9mg",
      "type": "whatsapp_template.status_changed",
      "language": "en-US",
      "version_id": "wav_01krdgeqcxet5s7t44vh8rt9mg",
      "summary": "Status changed to paused.",
      "metadata": {
        "from": "approved",
        "to": "paused"
      },
      "created_at": "2026-11-18T14:02:11Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Path parameters

- `template_ref` (string, required): Template ID (`wat_` prefix) or slug. A value that parses as a valid ID resolves by ID; any other value resolves as a slug.

## Query parameters

- `language` (string, optional): Return only this language's events. A BCP-47 tag; case and separator differences are accepted and normalized.
- `limit` (integer, optional): Maximum number of items to return per page.
- `starting_after` (string, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string, optional): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

## Header parameters

- `X-Workspace-Id` (string, optional): Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
- `X-Organization-Id` (string, optional): Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

## Response body

- `data` (array of object, required): Page of template events, newest first.
- `data.id` (string, required): Event ID.
- `data.type` (string, required)

  Type of template event. `whatsapp_template.status_changed` records a status WhatsApp gave the language. `whatsapp_template.quality_updated` records a change in its quality rating. Open enum: new event types may be added over time, so treat any unrecognized value as a future event rather than an error. The values below are the types known at this version.

  Possible values (may grow over time): `whatsapp_template.status_changed`, `whatsapp_template.quality_updated`
- `data.language` (string, required): Language the event concerns, as a BCP-47 tag.
- `data.version_id` (string, required): Version whose language changed. A pause or a quality change applies to the version that is sending, when one exists, which is not always the newest one.
- `data.summary` (string, required): Human-readable summary of what changed.
- `data.metadata` (object, required): Structured details for the event. `from` and `to` carry the values that changed: a language status for `whatsapp_template.status_changed`, or a quality score for `whatsapp_template.quality_updated`. `from` is the value Bird held before the change, and is absent when Bird held none. A change to `rejected` also carries the `rejection`, in the same shape as the language, when WhatsApp gave a reason. A new pause on a language that was already paused has the same `from` and `to`.
- `data.created_at` (string, required): When Bird recorded the event.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)
