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.
Create
Section titled “Create”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 |
HEADERacceptsformatTEXT,IMAGE,VIDEO,DOCUMENTorLOCATION.BUTTONSacceptsQUICK_REPLY,URL,PHONE_NUMBER,COPY_CODE,OTP,FLOW,CATALOG,MPMandVOICE_CALLbuttons.- 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 returns400validation_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.
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" } ] } ]}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const template = await messajo.templates.create({ 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" } ] } ]});n8n HTTP Request node settings
- Method:
POST - URL:
https://api.messajo.com/v1/templates - Authentication: Generic Credential Type, then Header Auth. Name:
Authorization; Value:Bearer mj_... - Headers: turn on Send Headers and add
Idempotency-Key(a unique value per item) - Body: turn on Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "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" } ] } ]}Replace mj_... with your API key.
The response is 201 with the template: id (tpl_…), status, category, components, and rejected_reason when it was rejected.
Lifecycle
Section titled “Lifecycle”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) andGET /v1/templates/{id}, with thereadpermission. - Edit:
PATCH /v1/templates/{id}changescomponentsorcategory. Meta only allows editing a template that isAPPROVED,REJECTEDorPAUSED, 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/syncdoes 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.
Body variables
Section titled “Body variables”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" } ] } ] }}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ 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" } ] } ] }});n8n HTTP Request node settings
- Method:
POST - URL:
https://api.messajo.com/v1/messages - Authentication: Generic Credential Type, then Header Auth. Name:
Authorization; Value:Bearer mj_... - Headers: turn on Send Headers and add
Idempotency-Key(a unique value per item) - Body: turn on Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "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" } ] } ] }}Replace mj_... with your API key.
Image header
Section titled “Image header”For a template with an image header, pass the image as a public link.
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" } ] } ] }}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ 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" } ] } ] }});n8n HTTP Request node settings
- Method:
POST - URL:
https://api.messajo.com/v1/messages - Authentication: Generic Credential Type, then Header Auth. Name:
Authorization; Value:Bearer mj_... - Headers: turn on Send Headers and add
Idempotency-Key(a unique value per item) - Body: turn on Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "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" } ] } ] }}Replace mj_... with your API key.
URL button with a dynamic suffix
Section titled “URL button with a dynamic suffix”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".
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" } ] } ] }}'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ 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" } ] } ] }});n8n HTTP Request node settings
- Method:
POST - URL:
https://api.messajo.com/v1/messages - Authentication: Generic Credential Type, then Header Auth. Name:
Authorization; Value:Bearer mj_... - Headers: turn on Send Headers and add
Idempotency-Key(a unique value per item) - Body: turn on Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "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" } ] } ] }}Replace mj_... with your API key.
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.
Errors
Section titled “Errors”| 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.