SMS templates

A template is a pre-registered message body you send by reference instead of inlining the text on every call. It carries its own category and a set of typed variable slots, so a send only supplies the values that change (an OTP code, an order number) and Bird assembles the final message. The catalogue you can send from includes Bird's built-in system templates and any templates authored for your workspace.

Sending from a template also settles compliance up front: the message category comes from the template, so opt-out (STOP) handling, quiet-hours, and per-country rules are decided by the template rather than by each caller.

Browsing templates in the dashboard

The Templates tab, under SMS, lists every template available to your workspace. Search by name and filter by status or category to find one.

The SMS Templates tab: a search box with Status and Category filters above a table of templates, each row showing a name, an Active status, a category, an EN locale chip, and a System scope, across Name, Status, Category, Locale, Scope, and Updated columns.

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

Name — the human-readable title, with the template's stable reference (for example order_notification) below it. The reference is what you pass when sending; it never changes.
Status — the template's lifecycle state. Active templates are live and sendable; Draft, Pending, Approved, and Rejected track a workspace template through review. Built-in system templates are always Active.
Category — the content classification (transactional, marketing, authentication, or service) applied to every message sent from the template.
Locale — the languages the template is stocked in, as BCP 47 tags. The first few are shown as chips with a +N overflow when a template is localized into many languages.
Scope — System for Bird's built-in templates, Workspace for ones your workspace authored.
Updated — when the template last changed. Built-in templates show no date.

What's in a template

Beyond the columns above, each template defines the variables it fills in at send time. A variable is a typed slot with a key (the name you supply a value under), a type, a required flag, and a human-readable constraint describing the accepted values. When you send, you supply a value for every required variable and no undeclared keys — a missing required variable or an unknown key is rejected.

A template is stocked in one or more locales. You pick one per send; if you request a language the template isn't stocked in, Bird falls back to the closest available language and then to English rather than failing.

Listing templates from the API

GET /v1/sms/templates returns the catalogue in full — it is small and not paginated. Filter by scope, category, or locale to narrow it:

Exemple de code

curl https://us1.platform.bird.com/v1/sms/templates?category=authentication \
  -H "Authorization: Bearer bk_us1_..."

Each template in the response carries its name (the reference you send by), scope, category, status, available_locales, the variables it expects, and a body preview of the default-language text. Fetch a single template by its reference with GET /v1/sms/templates/{template_ref} to read its variables before a send.

Sending with a template

Set the send's template object instead of text. The two are mutually exclusive, and because the category comes from the template, you omit category (and from is chosen for you unless you set it):

Exemple de code

curl -X POST https://us1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "template": {
      "name": "order_notification",
      "locale": "en",
      "parameters": { "order_id": "98765", "eta": "Tuesday" }
    }
  }'

name is the template reference from the catalogue. locale selects the localized body (omit for English). parameters supplies a value for each of the template's variables, keyed by variable name. Every required variable must be present and no undeclared key may appear, or the send is rejected with a 422. Everything else about the send — recipients, senders, tags, metadata, and the async 202 model — works exactly as it does for a free-text send.

Next steps

Sending SMS — the full send payload that the template field slots into
SMS log — find a sent message and follow its lifecycle
Events — the per-message event stream behind the log and webhooks