Templates
Templates: criar e enviar
Crie templates do WhatsApp com POST /v1/templates, acompanhe a aprovação da Meta e envie com type template, com variáveis, cabeçalho de mídia e botão de URL.
Template é uma mensagem com texto fixo e variáveis, aprovada pela Meta antes de poder ser usada. No WhatsApp ele é o único jeito de iniciar uma conversa ou de falar com o contato depois que a janela de 24 horas fechou (veja Janelas de conversa). Dentro da janela, você pode mandar texto livre ou qualquer outro tipo.
Esta página cobre templates de qualquer categoria. Para códigos de verificação, veja Templates de autenticação; para disparos em massa, Campanhas.
POST /v1/templates cria o template na conta do WhatsApp da conexão e o envia para a revisão da Meta. Precisa de uma chave com a permissão templates. No painel: Templates → Novo template.
| Campo | Regra |
|---|---|
connection_id |
Opcional com chave de conexão (mjc_…); obrigatório com chave de organização (mj_…) |
name |
Letras minúsculas, números e _ |
language |
Código da Meta, como pt_BR, en_US ou es |
category |
MARKETING, UTILITY ou AUTHENTICATION |
parameter_format |
Opcional: POSITIONAL ({{1}}) ou NAMED |
components |
Lista com no máximo um de cada: HEADER, BODY (com text, obrigatório), FOOTER e BUTTONS |
HEADERaceitaformatTEXT,IMAGE,VIDEO,DOCUMENTouLOCATION.BUTTONSaceita botõesQUICK_REPLY,URL,PHONE_NUMBER,COPY_CODE,OTP,FLOW,CATALOG,MPMeVOICE_CALL.- Os componentes seguem o formato de criação da Meta. Variáveis no texto precisam de um exemplo (
example), como no corpo abaixo. - Cabeçalho de mídia (
IMAGE,VIDEO,DOCUMENT) exige um arquivo de exemplo:components.HEADER.example.header_handle, o identificador devolvido pelo upload retomável da Meta. Sem ele a chamada volta400validation_failed. No painel, o Messajo faz esse upload quando você escolhe o arquivo.
Exemplo: corpo com duas variáveis, rodapé e um botão de resposta rápida.
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": "pedido_enviado", "language": "pt_BR", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.", "example": { "body_text": [ [ "Ana", "12345" ] ] } }, { "type": "FOOTER", "text": "Obrigado por comprar com a gente" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com a loja" } ] } ]}'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: "pedido_enviado", language: "pt_BR", category: "UTILITY", components: [ { type: "BODY", text: "Olá {{1}}, seu pedido {{2}} saiu para entrega.", example: { body_text: [ [ "Ana", "12345" ] ] } }, { type: "FOOTER", text: "Obrigado por comprar com a gente" }, { type: "BUTTONS", buttons: [ { type: "QUICK_REPLY", text: "Falar com a loja" } ] } ]});Configurações do nó HTTP Request do n8n
- Método:
POST - URL:
https://api.messajo.com/v1/templates - Autenticação: Generic Credential Type, depois Header Auth. Nome:
Authorization; Valor:Bearer mj_... - Cabeçalhos: ative Send Headers e adicione
Idempotency-Key(um valor único por item) - Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "name": "pedido_enviado", "language": "pt_BR", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.", "example": { "body_text": [ [ "Ana", "12345" ] ] } }, { "type": "FOOTER", "text": "Obrigado por comprar com a gente" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com a loja" } ] } ]}Substitua mj_... pela sua chave de API.
A resposta é 201 com o template: id (tpl_…), status, category, components e rejected_reason quando houver recusa.
Ciclo de vida
Seção intitulada “Ciclo de vida”Depois de criado, o template vai para a revisão da Meta. Cada mudança de status chega no evento template.status; consulte também GET /v1/templates/{id}.
| Status | O que significa |
|---|---|
PENDING |
Em revisão. Ainda não dá para enviar. |
APPROVED |
Aprovado. Pode ser enviado. |
REJECTED |
A Meta recusou; o motivo vem em rejected_reason. Edite e reenvie para revisão. |
PAUSED |
A Meta pausou por baixa qualidade. Não envia até voltar. |
DISABLED |
A Meta desativou. |
Há ainda IN_APPEAL, PENDING_DELETION, DELETED, ARCHIVED, LIMIT_EXCEEDED, LOCKED, FLAGGED e REINSTATED, que vêm da Meta como estão.
- Listar e consultar:
GET /v1/templates(com filtros e paginação) eGET /v1/templates/{id}, com a permissãoread. - Editar:
PATCH /v1/templates/{id}trocacomponentsoucategory. A Meta só deixa editar templateAPPROVED,REJECTEDouPAUSED, e um template aprovado não troca de categoria. - Excluir:
DELETE /v1/templates/{id}exclui na Meta e no Messajo. - Sincronizar: o Messajo relê os templates da Meta todo dia.
POST /v1/templates/syncfaz a leitura na hora; o template que sumiu da Meta fica marcado como excluído.
POST /v1/messages com type: "template":
| Campo | Regra |
|---|---|
template.name |
Nome do template, de 1 a 512 caracteres |
template.language |
Código do idioma, como pt_BR |
template.components |
Opcional. Valores das variáveis, no formato de envio da Meta: o Messajo repassa como você escreveu |
Os campos comuns (to, reply_to, typing…) estão em Campos comuns. Template não depende da janela de 24 horas: sai a qualquer momento.
Variáveis do corpo
Seção intitulada “Variáveis do corpo”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": "pedido_enviado", "language": "pt_BR", "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: "pedido_enviado", language: "pt_BR", components: [ { type: "body", parameters: [ { type: "text", text: "Ana" }, { type: "text", text: "12345" } ] } ] }});Configurações do nó HTTP Request do n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticação: Generic Credential Type, depois Header Auth. Nome:
Authorization; Valor:Bearer mj_... - Cabeçalhos: ative Send Headers e adicione
Idempotency-Key(um valor único por item) - Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "pedido_enviado", "language": "pt_BR", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Ana" }, { "type": "text", "text": "12345" } ] } ] }}Substitua mj_... pela sua chave de API.
Cabeçalho de imagem
Seção intitulada “Cabeçalho de imagem”Para um template com cabeçalho de imagem, passe a imagem por link público.
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": "promo_da_semana", "language": "pt_BR", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://exemplo.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: "promo_da_semana", language: "pt_BR", components: [ { type: "header", parameters: [ { type: "image", image: { link: "https://exemplo.com/promo.jpg" } } ] }, { type: "body", parameters: [ { type: "text", text: "Ana" } ] } ] }});Configurações do nó HTTP Request do n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticação: Generic Credential Type, depois Header Auth. Nome:
Authorization; Valor:Bearer mj_... - Cabeçalhos: ative Send Headers e adicione
Idempotency-Key(um valor único por item) - Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "promo_da_semana", "language": "pt_BR", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://exemplo.com/promo.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Ana" } ] } ] }}Substitua mj_... pela sua chave de API.
Botão de URL com sufixo dinâmico
Seção intitulada “Botão de URL com sufixo dinâmico”Quando a URL do botão termina em {{1}}, mande o sufixo em um componente button com sub_type: "url". index é a posição do botão, a partir de "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": "acompanhar_pedido", "language": "pt_BR", "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: "acompanhar_pedido", language: "pt_BR", components: [ { type: "button", sub_type: "url", index: "0", parameters: [ { type: "text", text: "12345" } ] } ] }});Configurações do nó HTTP Request do n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticação: Generic Credential Type, depois Header Auth. Nome:
Authorization; Valor:Bearer mj_... - Cabeçalhos: ative Send Headers e adicione
Idempotency-Key(um valor único por item) - Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "acompanhar_pedido", "language": "pt_BR", "components": [ { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "12345" } ] } ] }}Substitua mj_... pela sua chave de API.
A resposta é a mesma do envio de texto (201, status: "queued"); veja Resposta.
A Meta cobra por mensagem de template, conforme a categoria. Veja Custos da Meta.
| Erro | Quando | O que fazer |
|---|---|---|
422 template_error |
A Meta recusou o template ou os parâmetros (códigos 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) | Leia details[].message: diz qual item falhou |
404 template_not_found |
O template não existe | Confira name e language; rode POST /v1/templates/sync |
422 marketing_limit_reached |
A Meta limitou marketing para esse contato (131049) | Não reenvie logo em seguida |
429 meta_spam_rate_limited |
Limite por spam (131048) | Nunca reenvie |
402 meta_payment_required |
Problema de pagamento na conta da Meta (131042) | Corrija a forma de pagamento |
Mais passos em Falhas de envio.