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. Today the catalogue is Bird's built-in system templates — a fixed set covering common authentication and transactional messages. Authoring your own workspace templates is coming soon.

Templates are the generally-available way to send SMS today; sending free-form text is still in preview. 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 language chip, and a System scope, across Name, Status, Category, Language, 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 bird_order_confirmation) below it. The reference is what you pass when sending; it never changes.
Status — the template's lifecycle state. Built-in system templates are always Active — live and sendable. The Draft, Pending, Approved, and Rejected states track a workspace-authored template through review, and apply once workspace templates are available.
Category — the content classification (transactional, marketing, authentication, or service) applied to every message sent from the template.
Language — 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. Every template is System today; Workspace (templates your own workspace authors) is coming soon.
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 languages. 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 language to narrow it:

Code example

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_languages, 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 template decides the message, category, from, and media_urls are not accepted alongside it — the category comes from the template and Bird selects the sender:

Code example

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": "bird_otp_verification_ttl",
      "language": "en",
      "parameters": { "code": "481920", "ttl": "10" }
    }
  }'

name is the template reference from the catalogue (you can identify a template by its id instead). language 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 — the recipient, 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