whatsapp-templates

List available message templates

Returns the WhatsApp message templates available to your workspace: both the workspace's own templates (scope: workspace) and our built-in, Meta-approved templates (scope: system); filter to one tier with scope. Each entry carries the template's slug (the handle you reference when sending), its aggregated status, and the languages a send can currently resolve. It also summarizes where every language stands at Meta, so a list page can show an accurate row without another request. Content is not here: it lives under a version. The list is cursor-paginated. With no scope, the workspace's own templates come first, newest first, followed by our built-in templates.

get/v1/whatsapp/templates

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/whatsapp/templates
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

wabastring
Example:102290129340398

Filter to a single WhatsApp Business Account by its Meta WABA ID: the same value each template reports in its own waba field. Our built-in templates belong to no account and are never returned when this is set, and an account your workspace does not hold returns an empty page.

statusTemplateStatus[]

Filter by lifecycle status. Repeat the parameter to match any of several. Our built-in templates are always active.

[
  "active"
]
scope'system' | 'workspace'

Whether the template is one of our built-in templates (system) or one your workspace created (workspace).

Filter by ownership tier: system for the built-in, Meta-approved template catalog, or workspace for the workspace's own templates. Omit to return both.

categorystring

Meta's content classification for a template.

  • authentication: delivers one-time passcodes.
  • utility: delivers transaction-triggered updates (receipts, order status).
  • marketing: carries promotional content.

The category determines the sender number and price. This is an open enum. Accept unrecognized values.

Filter by template category.

qstring

A case-insensitive substring search across the template's slug, name, and description.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

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.

Headers

X-Workspace-Idstring

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-Idstring

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

The message templates available to your workspace.

next_cursorstring nullable required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursorstring nullable required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursorstring nullable 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.

Example response

{
  "data": [
    {
      "id": "wat_01krdgeqcxet5s7t44vh8rt9mg",
      "slug": "welcome-email",
      "name": "Order update",
      "description": "Sent when an order ships.",
      "waba": "102290129340398",
      "status": "active",
      "default_language": "pt-BR",
      "on_missing_language": "fallback",
      "available_languages": [
        "pt-BR"
      ],
      "languages": {
        "en": {
          "status": "approved"
        }
      },
      "draft_version_id": "wav_01krdgeqcxet5s7t44vh8rt9mg",
      "live_version_id": "wav_01krdgeqcxet5s7t44vh8rt9mg",
      "pending_version_id": "wav_01krdgeqcxet5s7t44vh8rt9mg",
      "last_submitted_at": "2026-07-26T16:40:00Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Changes

No recorded changes to this operation across all 3 revisions of this API.