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, sincronizar 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, LIST ou SYNC). 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",
    "components": [
      {
        "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"]
          }
        ]
      }
    ]
  }
}

Com header de imagem e botão de resposta rápida:

{
  "channelId": "uuid-do-canal-oficial",
  "correlationId": "template-boas-vindas-imagem",
  "content": {
    "type": "TEMPLATES",
    "commandType": "CREATE",
    "name": "boas_vindas_imagem",
    "language": "pt_BR",
    "category": "MARKETING",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": { "header_handle": ["https://exemplo.com/banner.png"] }
      },
      {
        "type": "BODY",
        "text": "Bem-vindo, {{1}}!",
        "example": { "body_text": [["Maria"]] }
      },
      {
        "type": "FOOTER",
        "text": "Equipe Loja do João"
      },
      {
        "type": "BUTTONS",
        "buttons": [{ "type": "QUICK_REPLY", "text": "Falar com a gente" }]
      }
    ]
  }
}

components é um array de objetos. O antigo componentsJson (string com o JSON dentro) foi substituído e não é mais lido.

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.

object[]

required

Array tipado de componentes do template. Cada item tem um type que determina a seção (HEADER, BODY, FOOTER, BUTTONS ou CAROUSEL) e os campos específicos daquela seção. A MessageFy valida a estrutura antes de repassar à Meta, recusando payloads inválidos com HTTP 400.

Componentes (`components`)

Cada item de components é um objeto com type discriminando a seção do template. Os valores de type são em MAIÚSCULAS. O conteúdo depende do format: em TEXT vai em text; em IMAGE, VIDEO ou DOCUMENT a mídia vai em example.header_handle.

string

required

Formato do cabeçalho: TEXT, IMAGE, VIDEO, DOCUMENT ou LOCATION.

string

Texto do cabeçalho. Obrigatório quando format é TEXT.

object

Exemplos exigidos pela Meta. Para TEXT, use header_text (lista de strings); para mídia, use header_handle (lista de URLs ou data URIs base64).

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Olá, {{1}}!",
  "example": { "header_text": ["João"] }
}

`BODY` — Corpo

Único componente obrigatório. Contém o texto principal do template com variáveis posicionais ({{1}}, {{2}}, …). Variáveis nomeadas ({{nome}}) não são aceitas.

string

required

Texto do corpo com variáveis. Em AUTHENTICATION não envie (veja abaixo).

object

Exemplos das variáveis em body_text: lista de listas (um conjunto de valores por exemplo).

boolean

Apenas em AUTHENTICATION: acrescenta ao corpo o aviso de não compartilhar o código. O texto é escrito pela Meta (localizado por idioma).

{
  "type": "BODY",
  "text": "Seu pedido {{1}} foi confirmado.",
  "example": { "body_text": [["10245"]] }
}

Texto puro, sem variáveis.

string

required

Texto do rodapé. Em AUTHENTICATION não envie (veja abaixo).

integer

Apenas em AUTHENTICATION: validade do código em minutos (1 a 90). A Meta transforma esse valor no texto do rodapé.

{
  "type": "FOOTER",
  "text": "Loja do João"
}

`BUTTONS` — Botões

Bloco de botões do template.

object[]

required

Lista de botões. Até 10 botões; máximo 2 URL e 1 PHONE_NUMBER.

Cada botão tem:

string

required

Tipo do botão: QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE ou OTP (este apenas em AUTHENTICATION).

string

Rótulo exibido no botão. Obrigatório em todos os tipos, exceto OTP (a Meta preenche um rótulo localizado).

string

Destino do botão URL. Aceita uma variável no final ({{1}}).

string

Telefone do botão PHONE_NUMBER, em formato internacional (ex.: +5511999999999).

string[]

Exemplos da variável do botão URL.

string

Como o código é entregue no botão OTP: COPY_CODE, ONE_TAP ou ZERO_TAP.

string

Pacote do app Android que recebe o código (OTP ONE_TAP/ZERO_TAP).

string

Hash de assinatura do app Android (OTP ONE_TAP/ZERO_TAP).

string

Rótulo do botão de autopreenchimento (OTP ONE_TAP/ZERO_TAP). Opcional na Meta.

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Acompanhar pedido",
      "url": "https://lojadojoao.com.br/pedidos/{{1}}",
      "example": ["10245"]
    }
  ]
}

`CAROUSEL` — Carrossel

Cartões de um template carrossel. A Meta exige que todos os cartões tenham a mesma estrutura.

object[]

required

Lista de cartões. Cada cartão tem components: HEADER de mídia (IMAGE ou VIDEO) + BODY e, opcionalmente, BUTTONS. A ordem da lista define a posição; card_index é opcional.

Regras de estrutura (Meta)

Regra	Detalhe
`components`	Exatamente um `BODY`; no máximo um de cada: `HEADER`, `FOOTER`, `BUTTONS`, `CAROUSEL`
Variáveis	Só posicionais (`{{1}}`, `{{2}}`, …); 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`
`CAROUSEL`	Até 10 cartões, todos com a mesma estrutura; cartão não tem `FOOTER`

Templates de autenticação (`AUTHENTICATION`)

Na categoria AUTHENTICATION a Meta escreve o texto do template a partir do código de uso único, então as regras mudam:

Sem HEADER e sem CAROUSEL.
BODY sem text; use só add_security_recommendation (opcional).
FOOTER sem text; use só code_expiration_minutes (1 a 90, opcional).
Exatamente um BUTTONS, com um botão OTP (otp_type: COPY_CODE, ONE_TAP ou ZERO_TAP). ONE_TAP e ZERO_TAP exigem package_name e signature_hash.

{
  "channelId": "uuid-do-canal-oficial",
  "content": {
    "type": "TEMPLATES",
    "commandType": "CREATE",
    "name": "codigo_verificacao",
    "language": "pt_BR",
    "category": "AUTHENTICATION",
    "components": [
      { "type": "BODY", "add_security_recommendation": true },
      { "type": "FOOTER", "code_expiration_minutes": 10 },
      { "type": "BUTTONS", "buttons": [{ "type": "OTP", "otp_type": "COPY_CODE" }] }
    ]
  }
}

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",
      "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "boas_vindas_cliente",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "Pending",
      "metaStatus": "PENDING",
      "qualityScore": "UNKNOWN",
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "Olá, {{1}}!"
        },
        {
          "type": "BODY",
          "text": "Seu pedido {{1}} foi confirmado..."
        }
      ],
      "wabaId": "104857392019283",
      "wabaTemplateId": "1523498712340987",
      "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",
        "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "boas_vindas_cliente",
        "language": "pt_BR",
        "category": "UTILITY",
        "status": "Approved",
        "metaStatus": "APPROVED",
        "qualityScore": "GREEN",
        "components": [
          {
            "type": "BODY",
            "text": "Seu pedido {{1}} foi confirmado..."
          }
        ],
        "wabaId": "104857392019283",
        "wabaTemplateId": "1523498712340987",
        "createdAt": "2026-08-19T14:20:44Z"
      },
      {
        "id": "a1c2e3f4-5b6d-4e7f-8a90-1b2c3d4e5f60",
        "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "promo_black_friday",
        "language": "pt_BR",
        "category": "MARKETING",
        "status": "Rejected",
        "metaStatus": "REJECTED",
        "qualityScore": "RED",
        "rejectionReason": "INVALID_FORMAT: o texto contém formatação não permitida",
        "error": {
          "code": "TEMPLATE_REJECTED",
          "title": "INVALID_FORMAT",
          "message": "O texto contém formatação não permitida",
          "summary": "INVALID_FORMAT: O texto contém formatação não permitida"
        }
      }
    ]
  }
}

Campos de cada template: id, businessId, name, language, category, components (array tipado de componentes), status, metaStatus, qualityScore, rejectionReason, error (detalhe estruturado da rejeição), wabaId, wabaTemplateId, createdAt, updatedAt, deletedAt.

Quando os componentes de um template não puderem ser tipados (um formato novo da Meta que ainda não existe no protocolo), o template vem com components: null e um componentsError descrevendo a falha. Os demais templates da listagem vêm normais — a falha é contida no template afetado.

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.

Sincronizar templates

Use SYNC quando o webhook de status de um template não chegou (o template parece preso em um estado antigo) ou para forçar uma reconciliação completa com a Meta. O comando pede ao provider que rebusque todos os templates e atualize status, qualidade, motivo de reprovação e componentes. Sem wabaPhoneNumberId, o SYNC varre todas as WABAs conectadas do business; com o campo, restringe à WABA desse número.

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

Com filtro por WABA:

{
  "channelId": "uuid-do-canal-oficial",
  "content": {
    "type": "TEMPLATES",
    "commandType": "SYNC",
    "wabaPhoneNumberId": "104857392019283"
  }
}

string

Opcional. Restringe a sincronização à WABA associada a este número. Quando omitido, todas as WABAs conectadas do business são sincronizadas.

Webhook de resposta

O resultado chega como TEMPLATES_SYNC_RESPONSE, com contadores consolidados e o detalhe por WABA:

{
  "correlationId": "sync-templates",
  "channelId": "uuid-do-canal-oficial",
  "content": {
    "type": "TEMPLATES_SYNC_RESPONSE",
    "commandType": "TEMPLATES_SYNC_RESPONSE",
    "success": true,
    "imported": 3,
    "updated": 5,
    "unchanged": 12,
    "skipped": 0,
    "totalFromMeta": 20,
    "wabas": [
      {
        "wabaId": "104857392019283",
        "success": true,
        "imported": 3,
        "updated": 5,
        "unchanged": 12,
        "skipped": 0,
        "totalFromMeta": 20,
        "error": null
      }
    ]
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	`true` quando pelo menos uma WABA sincronizou com sucesso. `false` apenas quando todas falham
`error`	`string` \| `null`	Descrição do erro global, quando `success` é `false`
`imported`	`integer`	Templates novos inseridos na base (soma de todas as WABAs)
`updated`	`integer`	Templates existentes que tiveram status/componentes atualizados
`unchanged`	`integer`	Templates já sincronizados e sem mudanças
`skipped`	`integer`	Templates ignorados pelo provider (ex.: em estados transitórios)
`totalFromMeta`	`integer`	Total de templates retornados pela Meta
`wabas`	`object[]` \| `null`	Detalhe por WABA, com os mesmos contadores e um `error` local

Campos de cada item em wabas: wabaId, success, imported, updated, unchanged, skipped, totalFromMeta e error (string | null, descreve a falha daquela WABA quando success é false).

O SYNC é a principal ferramenta de troubleshooting quando um template criado pela Meta não dispara o TEMPLATE_STATUS esperado. Rode um SYNC antes de investigar mais a fundo.

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

Cobranças

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Gerenciar Templates

Gerenciar Templates

Criar template

Componentes (`components`)

`HEADER` — Cabeçalho

`BODY` — Corpo

`FOOTER` — Rodapé

`BUTTONS` — Botões

`CAROUSEL` — Carrossel

Regras de estrutura (Meta)

Templates de autenticação (`AUTHENTICATION`)

Webhook de resposta

Acompanhar a aprovação (TEMPLATE_STATUS)

Listar templates

Sincronizar templates

Webhook de resposta

Motivos comuns de rejeição

​Gerenciar Templates

​Criar template

​Componentes (components)

​HEADER — Cabeçalho

​BODY — Corpo

​FOOTER — Rodapé

​BUTTONS — Botões

​CAROUSEL — Carrossel

​Regras de estrutura (Meta)

​Templates de autenticação (AUTHENTICATION)

​Webhook de resposta

​Acompanhar a aprovação (TEMPLATE_STATUS)

​Listar templates

​Sincronizar templates

​Webhook de resposta

​Motivos comuns de rejeição

Gerenciar Templates

Criar template

Componentes (`components`)

`HEADER` — Cabeçalho

`BODY` — Corpo

`FOOTER` — Rodapé

`BUTTONS` — Botões

`CAROUSEL` — Carrossel

Regras de estrutura (Meta)

Templates de autenticação (`AUTHENTICATION`)

Webhook de resposta

Acompanhar a aprovação (TEMPLATE_STATUS)

Listar templates

Sincronizar templates

Webhook de resposta

Motivos comuns de rejeição