Templates

Register message templates and read back the sendable ones with the parameters each takes — what a send outside the customer window needs, and what an agent is handed as tool schemas.

ModelsExpand Collapse

Template object { category, created_at, language, 9 more }

One registered message template in any status, with the parameters it takes.

A template is identified by its name and language together — that is the pair a template part names, and the pair this API addresses it by. There is no separate template id.

category: string

utility, marketing or authentication — the category the channel ASSIGNED, which may not be the one that was requested: a template that reads as marketing is recategorised on review, and the category is what a send is priced at. Values grow additively.

created_at: string

formatdate-time

language: string

The locale this variant is written in, such as en_US.

maxLength32

name: string

Lowercase letters, digits and underscores. Permanent once submitted.

maxLength512

parameters: unknown

The variables this template takes, as a JSON Schema (2020-12) object — ready to hand to a model verbatim as a tool schema. Every property is a string and every one is required: the channel substitutes all of them.

Each property publishes minLength, maxLength and pattern alongside its example, so a model sees the same value rules the send path enforces: values are 1–1024 characters, not whitespace-only, and contain no line break, tab or run of four spaces.

An empty properties object means the template takes no variables. null means something different and specific: this template’s variables cannot be addressed by name over this API (they are positional, or they live in a part of the template this API does not read yet). A template part naming such a template cannot supply its variables.

quality: string

The channel’s quality signal for this template, when it has one. null until it does. Free text; treat an unknown value as no signal.

rejected_reason: string

Why the template was refused or held, when the channel said. Free text for a human; the wording is not stable and must not be branched on. null when there is nothing to say.

send_schema: unknown

The complete schema for the template part that sends this exact template, including its fixed identity, named parameters, media header, and carousel values. null means this template cannot be addressed safely through this API.

status: string

Where this template stands. Only approved may be sent.

draft — a submission attempt has not produced a registered template. Consult retry_allowed; draft status alone never permits resubmission. pending — under review. Review is an unbounded queue; an hour or more is ordinary for a first submission. approved — sendable. rejected — refused; rejected_reason may say why. paused — was approved and is currently held, usually for quality. Not terminal: it can become approved again without you doing anything. disabled — no longer usable.

Values grow additively, and anything you do not recognise is not sendable.

updated_at: string

formatdate-time

content: optional object { body, buttons, carousel, 2 more }

Human-readable copy and fixed actions in a registered template.

body: optional string

buttons: optional array of object { type, phone_number, text, url }

type: string

The action kind; values grow additively.

phone_number: optional string

A fixed telephone destination baked into the template, when present.

text: optional string

The label shown to the recipient, when the channel supplies one.

url: optional string

A fixed destination baked into the template, when present.

carousel: optional array of object { body, buttons, header }

body: optional string

buttons: optional array of object { type, phone_number, text, url }

type: string

The action kind; values grow additively.

phone_number: optional string

A fixed telephone destination baked into the template, when present.

text: optional string

The label shown to the recipient, when the channel supplies one.

url: optional string

A fixed destination baked into the template, when present.

header: optional object { kind, text }

A media or text header as it will appear to the recipient.

kind: string

text, image, video, or document; values grow additively.

text: optional string

Fixed header copy. Omitted for media headers.

footer: optional string

header: optional object { kind, text }

A media or text header as it will appear to the recipient.

kind: string

text, image, video, or document; values grow additively.

text: optional string

Fixed header copy. Omitted for media headers.

retry_allowed: optional boolean

Whether another submission using this draft’s name and language is currently allowed. A corrected definition may be required. Present on all responses from current servers. Clients must not offer retry unless this is explicitly true.

TemplatePage object { data, has_more, next_cursor }

One page of templates, newest first.

data: array of Template { category, created_at, language, 9 more }

category: string

created_at: string

formatdate-time

language: string

The locale this variant is written in, such as en_US.

maxLength32

name: string

Lowercase letters, digits and underscores. Permanent once submitted.

maxLength512

parameters: unknown

quality: string

The channel’s quality signal for this template, when it has one. null until it does. Free text; treat an unknown value as no signal.

rejected_reason: string

Why the template was refused or held, when the channel said. Free text for a human; the wording is not stable and must not be branched on. null when there is nothing to say.

send_schema: unknown

status: string

Where this template stands. Only approved may be sent.

Values grow additively, and anything you do not recognise is not sendable.

updated_at: string

formatdate-time

content: optional object { body, buttons, carousel, 2 more }

Human-readable copy and fixed actions in a registered template.

body: optional string

buttons: optional array of object { type, phone_number, text, url }

type: string

The action kind; values grow additively.

phone_number: optional string

A fixed telephone destination baked into the template, when present.

text: optional string

The label shown to the recipient, when the channel supplies one.

url: optional string

A fixed destination baked into the template, when present.

carousel: optional array of object { body, buttons, header }

body: optional string

buttons: optional array of object { type, phone_number, text, url }

type: string

The action kind; values grow additively.

phone_number: optional string

A fixed telephone destination baked into the template, when present.

text: optional string

The label shown to the recipient, when the channel supplies one.

url: optional string

A fixed destination baked into the template, when present.

header: optional object { kind, text }

A media or text header as it will appear to the recipient.

kind: string

text, image, video, or document; values grow additively.

text: optional string

Fixed header copy. Omitted for media headers.

footer: optional string

header: optional object { kind, text }

A media or text header as it will appear to the recipient.

kind: string

text, image, video, or document; values grow additively.

text: optional string

Fixed header copy. Omitted for media headers.

retry_allowed: optional boolean

has_more: boolean

True when another page follows.

next_cursor: optional string

Pass as cursor to read the next page. Present only when has_more is true.

Templates

Register a template

List templates

ModelsExpand Collapse