WhatsApp Business Templates

Outside WhatsApp’s 24-hour customer-service window Meta only delivers approved message templates, so these endpoints are what allow business-initiated messaging at all. Templates live at Meta on the connected WhatsApp Business Account (WABA), and Brainstormer keeps a local mirror so a send decision never needs a Graph API round trip. Every endpoint below resolves the agent’s connected channel to its WABA first; an agent with no active WhatsApp Business connection gets a 404.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

Meta reviews templates asynchronously. A create returns immediately with status: "PENDING" — never APPROVED — and the verdict arrives later on Meta’s message_template_status_update webhook, which Brainstormer records automatically. Only a template whose status is APPROVED can be sent.

List Templates

Reconciles the local mirror from Meta and returns the result. This makes a Graph API call, so it is slower than a local read — don’t poll it.

Response (200)

object[]

Show Template object

string

Brainstormer’s id for the local row.

string | null

Meta’s own template id, when known.

string

Meta’s template name (lowercase letters, digits and underscores).

string

Meta language code, e.g. en_US.

string

MARKETING, UTILITY or AUTHENTICATION. Meta may change this during review.

string

Meta’s review status, verbatim: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, FLAGGED, IN_APPEAL, ARCHIVED, LOCKED, LIMIT_EXCEEDED, PENDING_DELETION, DELETED or UNKNOWN.

string | null

Meta’s reason for a rejection or pause.

string | null

ISO timestamp of the last status change.

string

POSITIONAL ({{1}}) or NAMED ({{customer_name}}).

object[]

Meta’s component definitions, verbatim.

object

What must be supplied to send this template. Derived from the definition, so it can never go stale.

Show fill

string[]

Placeholder keys in the header text.

string[]

Placeholder keys in the body, in Meta’s fill order.

string | null

IMAGE, VIDEO or DOCUMENT when the header needs a media link.

boolean

True when nothing has to be supplied.

boolean

Whether this template can carry an operator’s reply — exactly one body placeholder and nothing else to fill.

string

ISO timestamp.

object | null

The template currently configured to carry operator replies outside the window, as { name, language }.

object

A ready-made draft the UI offers as a starting point.

Errors

Status	Code	Meaning
`404`	`whatsapp_business_not_connected`	The agent has no active WhatsApp Business connection.
`409`	`whatsapp_business_waba_unknown`	The connection predates WABA-id recording; reconnect the number.
`502`	`whatsapp_business_token_invalid`	Meta rejected the channel’s credentials — reconnect the channel.

Create a Template

Files a new template with Meta. Answers 201 with the stored template in its PENDING state.

Body

string

required

Lowercase letters, digits and underscores only, and unique on the WABA for this language.

string

required

Meta language code, e.g. en_US.

string

required

MARKETING, UTILITY or AUTHENTICATION.

string

required

The message text. Use {{1}}, {{2}} … for values supplied at send time. Meta rejects a body that is only a placeholder.

string

Optional header text, which may also carry placeholders.

string

Optional footer text. Cannot contain placeholders.

object

Sample values per placeholder, as { header?: { "1": "…" }, body?: { "1": "…" } }. Meta requires an example for every placeholder before a reviewer will look at the template.

Example

{
  "name": "support_follow_up",
  "language": "en_US",
  "category": "UTILITY",
  "body": "You have a new reply from our support team:\n\n{{1}}\n\nReply to this message to continue the conversation.",
  "examples": { "body": { "1": "Thanks for waiting — your order is on its way." } }
}

Errors

Status	Code	Meaning
`400`	`whatsapp_business_template_name_invalid`	The name is outside Meta’s alphabet.
`400`	`whatsapp_business_template_parameters_invalid`	A placeholder has no sample value, or the draft is otherwise malformed. Refused before any Graph call.
`400`	—	Meta refused the create (duplicate name, unsupported component).
`502`	`whatsapp_business_token_invalid`	Meta rejected the channel’s credentials.

Delete a Template

Deletes at Meta first, then locally. If this template was the configured fallback, that selection is cleared in the same request. Returns 204. A 404 with code whatsapp_business_template_not_found means the template is not on this account.

Set the Fallback Template

Chooses the approved template that carries an operator’s reply when the 24-hour customer-service window has closed. The operator’s own text is placed in the template’s single body placeholder.

Body

string

Template name. Omit (or send an empty body) to clear the selection.

string

Template language. Required when name is given.

Response (200)

object | null

{ name, language }, or null when cleared.

Errors

Status	Code	Meaning
`404`	`whatsapp_business_template_not_found`	No such template on this WABA.
`409`	`whatsapp_business_template_not_approved`	Meta has not approved it yet.
`409`	`whatsapp_business_template_shape_unsuitable`	It does not have exactly one body placeholder and nothing else to fill — there is nowhere to put the operator’s message.

A template send is billed twice over: Brainstormer’s own WHATSAPP_BUSINESS_CREDITS_PER_TEMPLATE_SEND platform fee, and Meta’s real per-message charge (recorded from the delivery-status webhook). A reply sent inside the 24-hour window incurs neither of those template charges.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

WhatsApp Business Templates

WhatsApp Business Templates

List Templates

Response (200)

Errors

Create a Template

Body

Errors

Delete a Template

Set the Fallback Template

Body

Response (200)

Errors

​WhatsApp Business Templates

​List Templates

​Response (200)

​Errors

​Create a Template

​Body

​Errors

​Delete a Template

​Set the Fallback Template

​Body

​Response (200)

​Errors

WhatsApp Business Templates

List Templates

Response (200)

Errors

Create a Template

Body

Errors

Delete a Template

Set the Fallback Template

Body

Response (200)

Errors