Skip to content

Templates

Templates: create and send

Create WhatsApp templates with POST /v1/templates, follow Meta's review, and send with type template, with variables, a media header and a URL button.

A template is a message with fixed text and variables that Meta must approve before you can use it. On WhatsApp it is the only way to start a conversation, or to reach a contact once the 24-hour window has closed (see Conversation windows). Inside the window you can send free-form text or any other type.

This page covers templates of any category. For verification codes see Authentication templates; for bulk sends see Campaigns.

POST /v1/templates creates the template in the connection’s WhatsApp account and sends it to Meta for review. It needs a key with the templates permission. In the panel: Templates → New template.

Field Rule
connection_id Optional with a connection key (mjc_…); required with an organization key (mj_…)
name Lowercase letters, digits and _
language Meta language code, such as pt_BR, en_US or es
category MARKETING, UTILITY or AUTHENTICATION
parameter_format Optional: POSITIONAL ({{1}}) or NAMED
components List with at most one of each: HEADER, BODY (with text, required), FOOTER and BUTTONS
  • HEADER accepts format TEXT, IMAGE, VIDEO, DOCUMENT or LOCATION.
  • BUTTONS accepts QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, OTP, FLOW, CATALOG, MPM and VOICE_CALL buttons.
  • Components follow Meta’s creation format. Variables in the text need an example, as in the body below.
  • A media header (IMAGE, VIDEO, DOCUMENT) requires an example file: components.HEADER.example.header_handle, the identifier returned by Meta’s resumable upload. Without it the call returns 400 validation_failed. In the panel, Messajo does that upload when you pick the file.

Example: a body with two variables, a footer and a quick-reply button.

Janela do terminal
curl https://api.messajo.com/v1/templates \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"connection_id": "conn_...",
"name": "order_shipped",
"language": "en_US",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} is out for delivery.",
"example": {
"body_text": [
[
"Ana",
"12345"
]
]
}
},
{
"type": "FOOTER",
"text": "Thanks for shopping with us"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Talk to the store"
}
]
}
]
}'

The response is 201 with the template: id (tpl_…), status, category, components, and rejected_reason when it was rejected.

Once created, the template goes to Meta’s review. Every status change arrives as the template.status event; you can also call GET /v1/templates/{id}.

Status Meaning
PENDING Under review. Cannot be sent yet.
APPROVED Approved. Can be sent.
REJECTED Meta rejected it; the reason is in rejected_reason. Edit it and send it for review again.
PAUSED Meta paused it for low quality. It will not send until it is back.
DISABLED Meta disabled it.

There are also IN_APPEAL, PENDING_DELETION, DELETED, ARCHIVED, LIMIT_EXCEEDED, LOCKED, FLAGGED and REINSTATED, which come from Meta as they are.

  • List and read: GET /v1/templates (with filters and pagination) and GET /v1/templates/{id}, with the read permission.
  • Edit: PATCH /v1/templates/{id} changes components or category. Meta only allows editing a template that is APPROVED, REJECTED or PAUSED, and an approved template cannot change category.
  • Delete: DELETE /v1/templates/{id} deletes it at Meta and in Messajo.
  • Sync: Messajo re-reads the templates from Meta every day. POST /v1/templates/sync does it right now; a template that vanished from Meta is marked as deleted.

POST /v1/messages with type: "template":

Field Rule
template.name Template name, 1 to 512 characters
template.language Language code, such as en_US
template.components Optional. Variable values, in Meta’s send format: Messajo passes them through as written

The common fields (to, reply_to, typing…) are in Common fields. A template does not depend on the 24-hour window: it can go out at any time.

Janela do terminal
curl https://api.messajo.com/v1/messages \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"connection_id": "conn_...",
"to": "5511999999999",
"type": "template",
"template": {
"name": "order_shipped",
"language": "en_US",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Ana"
},
{
"type": "text",
"text": "12345"
}
]
}
]
}
}'

For a template with an image header, pass the image as a public link.

Janela do terminal
curl https://api.messajo.com/v1/messages \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"connection_id": "conn_...",
"to": "5511999999999",
"type": "template",
"template": {
"name": "weekly_promo",
"language": "en_US",
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "https://example.com/promo.jpg"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Ana"
}
]
}
]
}
}'

When the button URL ends in {{1}}, send the suffix in a button component with sub_type: "url". index is the button position, starting at "0".

Janela do terminal
curl https://api.messajo.com/v1/messages \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"connection_id": "conn_...",
"to": "5511999999999",
"type": "template",
"template": {
"name": "track_order",
"language": "en_US",
"components": [
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "12345"
}
]
}
]
}
}'

The response is the same as for a text message (201, status: "queued"); see Response.

Meta charges for each template message, by category. See Meta costs.

Error When What to do
422 template_error Meta rejected the template or its parameters (codes 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) Read details[].message: it says which item failed
404 template_not_found The template does not exist Check name and language; run POST /v1/templates/sync
422 marketing_limit_reached Meta limited marketing for this contact (131049) Do not resend right away
429 meta_spam_rate_limited Spam rate limit (131048) Never resend
402 meta_payment_required Payment problem on the Meta account (131042) Fix the payment method

More steps in Send failures.