<Intro>

<EndpointHeader />

<Description>

Returns the SMS templates you can send from, including Bird's built-in templates. Filter by scope, category, or language; the catalogue is small and returned in full, so this list is not paginated. To read one template's variables before sending with it, use [Get an SMS template](/docs/api/reference/get-sms-template).

</Description>

</Intro>

<Parameters in="query">

<Parameter name="scope" type="string">

<Description>

Keep only templates of this scope: `system` for Bird's built-in templates, `workspace` for templates authored in your workspace. Omit for all. Workspace-authored SMS templates are not available yet, so `workspace` currently matches nothing.

</Description>

<Description>

Possible values: `system`, `workspace`

</Description>

</Parameter>

<Parameter name="category" type="string">

<Description>

Keep only templates whose `category` matches. Omit for all categories.

</Description>

<Description>

Possible values: `transactional`, `marketing`, `authentication`, `service`

</Description>

</Parameter>

<Parameter name="language" type="string">

<Description>

Keep only templates available in this language, as a BCP-47 tag. Matches the template's `available_languages` entries exactly, with no fallback.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

The templates available to your workspace. The catalogue is small and returned in full; this list is not paginated.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required>

<Description>

Unique identifier for the template.

</Description>

</Field>

<Field name="name" type="object" prefix="data." required>

<Description>

The template's stable handle. Pass it (or the id) as the template reference when sending.

</Description>

</Field>

<Field name="description" type="string" prefix="data." required>

<Description>

Human-readable description of what the template is for.

</Description>

</Field>

<Field name="scope" type="string" prefix="data." required>

<Description>

Whether the template is a built-in Bird template (`system`) or one your workspace authored (`workspace`).

</Description>

<Description>

Possible values: `system`, `workspace`

</Description>

</Field>

<Field name="category" type="object" prefix="data." required>

<Description>

Content classification applied to messages sent from this template.

</Description>

</Field>

<Field name="body" type="string" prefix="data." required>

<Description>

The template body in its default language, shown for preview. Variable placeholders appear inline (for example `{{ code }}`).

</Description>

</Field>

<Field name="variables" type="array of object" prefix="data." required>

<Description>

The typed slots this template fills in from the values you supply when sending.

</Description>

<FieldChildren kind="response">

<Field name="key" type="string" prefix="data.variables." required>

<Description>

The parameters key this slot is filled with.

</Description>

</Field>

<Field name="type" type="string" prefix="data.variables." required>

<Description>

The value type this slot accepts. Open enum — treat any unrecognized value as a future type rather than an error. SMS templates use the typed slots (`code`, `amount`, …); email templates use `text`.

</Description>

<Description>

Possible values (may grow over time): `code`, `ttl`, `count`, `ref`, `date`, `date_time`, `amount`, `currency`, `text`

</Description>

</Field>

<Field name="required" type="boolean" prefix="data.variables." required>

<Description>

Whether the slot must be supplied when sending. Advisory for email templates, where a missing value renders as empty rather than rejecting the send.

</Description>

</Field>

<Field name="constraint" type="string" prefix="data.variables." required>

<Description>

A human-readable description of the accepted values.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="available_languages" type="array of string" prefix="data." required>

<Description>

The languages this template is available in, as BCP-47 tags.

</Description>

</Field>

<Field name="status" type="string" prefix="data." required>

<Description>

The template's lifecycle state. `active` means the template can be sent; every built-in Bird template is `active`. `draft` (being edited), `pending` (submitted for review), `approved` (passed review), and `rejected` (failed review) describe a workspace-authored template's authoring lifecycle; workspace-authored SMS templates are not available yet, so today every template is `active`.

</Description>

<Description>

Possible values: `active`, `draft`, `pending`, `approved`, `rejected`

</Description>

</Field>

<Field name="draft_version_id" type="nullable string" prefix="data." required>

<Description>

The current editable draft version. Always null today: SMS templates are not yet versioned; present for parity with email templates.

</Description>

</Field>

<Field name="published_version_id" type="nullable string" prefix="data.">

<Description>

The currently published version, or null if the template has never been published. Always null today: SMS templates are not yet versioned; present for parity with email templates.

</Description>

</Field>

<Field name="revision" type="nullable integer" prefix="data." required>

<Description>

The draft's revision counter. Always null today: SMS templates are not yet versioned; present for parity with email templates.

</Description>

</Field>

<Field name="created_at" type="nullable string" prefix="data." required>

<Description>

When the template was created. Null for built-in templates.

</Description>

</Field>

<Field name="updated_at" type="nullable string" prefix="data." required>

<Description>

When the template was last updated. Null for built-in templates.

</Description>

</Field>

</FieldChildren>

</Field>

</Payload>