Gerenciar Templates

No canal do WhatsApp Oficial, conversas só podem ser iniciadas com um template aprovado pela Meta. Esta página cobre a gestão (criar, listar e acompanhar aprovação); o envio de mensagem a partir de um template aprovado está em Mensagem de Template. As operações usam POST /api/v1/message/SendCommand com content.type: "TEMPLATES", variando o commandType (CREATE ou LIST). Resposta síncrona: { "packageId": "..." }; resultado via webhook.

Criar template

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "template-boas-vindas",
  "content": {
    "type": "TEMPLATES",
    "commandType": "CREATE",
    "name": "boas_vindas_cliente",
    "language": "pt_BR",
    "category": "UTILITY",
    "componentsJson": "[{\"type\":\"HEADER\",\"format\":\"TEXT\",\"text\":\"Olá, {{1}}!\",\"example\":{\"header_text\":[\"João\"]}},{\"type\":\"BODY\",\"text\":\"Seu pedido {{1}} foi confirmado e será entregue em até {{2}} dias úteis.\",\"example\":{\"body_text\":[[\"10245\",\"3\"]]}},{\"type\":\"FOOTER\",\"text\":\"Loja do João\"},{\"type\":\"BUTTONS\",\"buttons\":[{\"type\":\"URL\",\"text\":\"Acompanhar pedido\",\"url\":\"https://lojadojoao.com.br/pedidos/{{1}}\",\"example\":[\"10245\"]}]}]"
  }
}

string

required

Nome do template em snake_case (minúsculas, dígitos e underscore), conforme as regras da Meta.

string

required

Locale da Meta (ex.: pt_BR, en_US).

string

required

Categoria da Meta: MARKETING, UTILITY ou AUTHENTICATION.

string

required

Estrutura dos componentes do template como string JSON (o array de componentes serializado). A MessageFy repassa o conteúdo de forma opaca à Meta, sem interpretar nem validar — monte-o seguindo o formato de componentes da WhatsApp Business Platform.

O campo é componentsJson e o valor é uma string contendo o JSON dos componentes — não um array. Enviar um array diretamente causa erro de desserialização (400).

Regras de estrutura (Meta)

Regra	Detalhe
`components`	Exatamente um `BODY`; no máximo um de cada: `HEADER`, `FOOTER`, `BUTTONS`
Variáveis	Toda `{{n}}` exige o `example` correspondente
`FOOTER`	Não aceita variáveis
`BUTTONS`	Até 10 botões; máximo 2 `URL` e 1 `PHONE_NUMBER`

Header com mídia: para format IMAGE, VIDEO ou DOCUMENT, informe a mídia em example.header_handle — URL pública http(s) ou data URI base64. Com data URI, a MessageFy sobe o arquivo para o storage e o substitui pela URL pública antes de enviar à Meta.

Webhook de resposta

{
  "correlationId": "template-boas-vindas",
  "content": {
    "type": "TEMPLATES_CREATE_RESPONSE",
    "commandType": "TEMPLATES_CREATE_RESPONSE",
    "success": true,
    "template": {
      "id": "7b3f9c21-4d18-4a6e-90f2-1c5e8a7b4d03",
      "name": "boas_vindas_cliente",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "Pending",
      "wabaId": "104857392019283",
      "createdAt": "2026-08-19T14:20:44Z"
    }
  }
}

Guarde o template.id — é o templateId usado no envio.

Acompanhar a aprovação (TEMPLATE_STATUS)

A decisão da Meta chega de forma espontânea (pode levar horas ou dias) pelo evento TEMPLATE_STATUS:

{
  "channelId": "uuid-do-canal-de-feedback",
  "content": {
    "type": "TEMPLATE_STATUS",
    "templateId": "7b3f9c21-4d18-4a6e-90f2-1c5e8a7b4d03",
    "providerTemplateId": "1523498712340987",
    "name": "boas_vindas_cliente",
    "wabaId": "104857392019283",
    "status": "APPROVED",
    "reason": null
  }
}

Campo	Tipo	Descrição
`templateId`	string	Id do template na MessageFy (o elo com o CREATE original)
`providerTemplateId`	string	Id do template no provedor (waba_template_id)
`name`	string	Nome do template
`wabaId`	string	WABA dona do template
`status`	string	Estado em MAIÚSCULAS, exatamente como a Meta enviou (`APPROVED`, `REJECTED`, `PENDING`, `PAUSED`, `DISABLED`, …)
`reason`	string \| null	Motivo, quando há (ex.: `INVALID_FORMAT`)

TEMPLATE_STATUS é um evento da conta, não de um número: a mesma WABA pode ter vários canais. Ele é entregue no canal de feedback do Router e não carrega correlationId/originPackageId — correlacione pelo templateId. O conjunto de status é governado pela Meta: compare por igualdade e trate valores desconhecidos como um estado novo, não como erro.

Listar templates

{
  "channelId": "uuid-do-canal-oficial",
  "content": { "type": "TEMPLATES", "commandType": "LIST" }
}

Webhook:

{
  "content": {
    "type": "TEMPLATES_LIST_RESPONSE",
    "commandType": "TEMPLATES_LIST_RESPONSE",
    "success": true,
    "count": 2,
    "templates": [
      {
        "id": "7b3f9c21-4d18-4a6e-90f2-1c5e8a7b4d03",
        "name": "boas_vindas_cliente",
        "language": "pt_BR",
        "category": "UTILITY",
        "status": "Approved",
        "components": "[{\"type\":\"BODY\",\"text\":\"Seu pedido {{1}} foi confirmado...\"}]",
        "wabaId": "104857392019283",
        "createdAt": "2026-08-19T14:20:44Z"
      },
      {
        "id": "a1c2e3f4-5b6d-4e7f-8a90-1b2c3d4e5f60",
        "name": "promo_black_friday",
        "language": "pt_BR",
        "category": "MARKETING",
        "status": "Rejected",
        "rejectionReason": "INVALID_FORMAT: o texto contém formatação não permitida"
      }
    ]
  }
}

Campos de cada template: id, whatsAppNumberId, name, language, category, components (string JSON, como devolvida pelo provedor), status, rejectionReason, wabaId, wabaTemplateId, createdAt, updatedAt.

O LIST devolve todos os templates do business (todos os números da WABA), não apenas os do número deste canal — o canal do pacote define de qual business vêm as credenciais. Filtre do seu lado se precisar. Não há filtro por número.

Para buscar um template, informe templateId no LIST:

{
  "channelId": "uuid-do-canal-oficial",
  "content": { "type": "TEMPLATES", "commandType": "LIST", "templateId": "7b3f9c21-4d18-4a6e-90f2-1c5e8a7b4d03" }
}

Id inexistente não é erro: a resposta vem com success: true, lista vazia e count: 0.

Motivos comuns de rejeição

A Meta rejeita templates por, entre outros: formatação inválida (INVALID_FORMAT), conteúdo que viola as políticas do WhatsApp, categoria incorreta para o conteúdo, variáveis sem exemplo, uso de conteúdo promocional em categoria UTILITY/AUTHENTICATION, links encurtados/suspeitos e nomes de template enganosos. Corrija e crie um novo template (não é possível editar um rejeitado).

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Gerenciar Templates

Gerenciar Templates

Criar template

Regras de estrutura (Meta)

Webhook de resposta

Acompanhar a aprovação (TEMPLATE_STATUS)

Listar templates

Motivos comuns de rejeição

​Gerenciar Templates

​Criar template

​Regras de estrutura (Meta)

​Webhook de resposta

​Acompanhar a aprovação (TEMPLATE_STATUS)

​Listar templates

​Motivos comuns de rejeição

Gerenciar Templates

Criar template

Regras de estrutura (Meta)

Webhook de resposta

Acompanhar a aprovação (TEMPLATE_STATUS)

Listar templates

Motivos comuns de rejeição