Pular para o conteúdo

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
  • HEADER aceita format TEXT, IMAGE, VIDEO, DOCUMENT ou LOCATION.
  • BUTTONS aceita botões QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, OTP, FLOW, CATALOG, MPM e VOICE_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 volta 400 validation_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.

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": "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"
}
]
}
]
}'

A resposta é 201 com o template: id (tpl_…), status, category, components e rejected_reason quando houver recusa.

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) e GET /v1/templates/{id}, com a permissão read.
  • Editar: PATCH /v1/templates/{id} troca components ou category. A Meta só deixa editar template APPROVED, REJECTED ou PAUSED, 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/sync faz 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.

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": "pedido_enviado",
"language": "pt_BR",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Ana"
},
{
"type": "text",
"text": "12345"
}
]
}
]
}
}'

Para um template com cabeçalho de imagem, passe a imagem por link público.

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": "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"
}
]
}
]
}
}'

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".

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": "acompanhar_pedido",
"language": "pt_BR",
"components": [
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "12345"
}
]
}
]
}
}'

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.