Atualizado em 25/10/2026
Um template da API do WhatsApp é uma mensagem pré-aprovada pela Meta e é o único tipo de mensagem que pode ser enviado fora da janela de atendimento de 24 horas. Você cria o template por API com nome, idioma, categoria (marketing, utilidade ou autenticação) e componentes; a Meta revisa em até 24 horas e, se aprovar, você envia preenchendo as variáveis. A categoria define o preço, e qualquer intenção promocional no texto faz a Meta tratar um template de utilidade como marketing.
Este guia mostra como montar, criar e enviar templates com payloads reais, por que eles são reprovados e como escrever avisos que continuem sendo utilidade.
Quando o template é obrigatório
A Cloud API separa dois tipos de mensagem. Mensagens livres (texto, imagem, botões, listas) só podem ser enviadas enquanto a janela de 24 horas está aberta, ou seja, depois que o usuário escreveu ou ligou para a empresa. Fora dela, só sai template aprovado.
Na prática, template é o que você usa para:
- avisar sobre um pedido, pagamento, agendamento ou mudança de conta;
- enviar código de verificação (OTP);
- mandar ofertas e campanhas para quem aceitou receber;
- retomar contato com quem não fala com você há mais de 24 horas.
As três categorias de template
Toda criação de template exige uma categoria. A Meta valida a escolha pelo conteúdo, e a categoria é usada na cobrança (veja os valores em quanto custa a API do WhatsApp no Brasil).
| Categoria | Para que serve | Exemplos aceitos | Pontos de atenção |
|---|---|---|---|
MARKETING | Divulgação, vendas, retargeting, promoção de app, relacionamento | Cupom, carrinho abandonado, renovação de assinatura com desconto, aniversário | Também recebe templates com conteúdo misto (aviso + promoção) ou vago, como só {{1}} |
UTILITY | Seguir uma ação ou pedido do usuário | Confirmação e rastreio de pedido, alerta de conta, lembrete de cobrança, pesquisa sobre um atendimento específico | Precisa ser não promocional e específico do usuário, ou essencial (segurança, recall, mudança de política de privacidade) |
AUTHENTICATION | Código de uso único para verificar identidade | “{{1}} é o seu código de verificação.” | Exige botão de OTP (copiar código ou preenchimento automático); sem URL, mídia ou emoji; parâmetros com até 15 caracteres |
Código de verificação só pode ir em template de autenticação. Quando a Meta detecta um template de marketing ou utilidade que deveria ser de autenticação, ela avisa e muda o status para REJECTED no primeiro dia do mês seguinte.
Anatomia: os componentes de um template
Um template tem até quatro componentes. Só o corpo é obrigatório.
| Componente | Obrigatório | Limites principais |
|---|---|---|
Cabeçalho (HEADER) | Não | Texto com até 60 caracteres e 1 parâmetro; ou mídia (imagem, vídeo, GIF, documento); ou localização (só utilidade e marketing) |
Corpo (BODY) | Sim | Até 1.024 caracteres, vários parâmetros |
Rodapé (FOOTER) | Não | Até 60 caracteres, só texto |
Botões (BUTTONS) | Não | Até 10 no total, com limites por tipo |
Os botões mais usados têm estas regras:
| Tipo de botão | Quantidade máxima | Detalhes |
|---|---|---|
QUICK_REPLY | 10 | Rótulo de até 25 caracteres; o toque envia o texto como mensagem do usuário |
URL | 2 | Rótulo de até 25 caracteres; URL de até 2.000 caracteres com 1 variável no final |
PHONE_NUMBER | 1 | Número de até 20 caracteres |
COPY_CODE | 1 | Texto copiado de até 20 caracteres (ex.: cupom) |
FLOW | — | Abre um WhatsApp Flow; rótulo de até 25 caracteres |
Respostas rápidas e outros botões precisam ficar agrupados (todas as respostas rápidas juntas). Templates com 4 ou mais botões, ou com resposta rápida misturada a outro tipo, não aparecem no WhatsApp para desktop: o usuário é orientado a abrir no celular. Com mais de três botões, a mensagem mostra dois e agrupa o resto em “Ver todas as opções”.
Como criar um template via API
Na Cloud API direta, a criação é um POST no endpoint message_templates da conta de mensagens (o antigo WABA; desde 23/09/2026, templates ficam na conta de mensagens, e os IDs de WABA existentes viraram IDs de conta de mensagens):
curl 'https://graph.facebook.com/v26.0/SEU_WABA_ID/message_templates' \
-H 'Authorization: Bearer TOKEN_DA_META' \
-H 'Content-Type: application/json' \
-d '{ "name": "...", "language": "pt_BR", "category": "UTILITY", "components": [ ... ] }'Na Vectalk, o corpo é o mesmo. Muda a URL base e o token: com um token de instância, o WABA é resolvido automaticamente e você não informa o ID na rota.
curl -X POST https://apis.vectalk.com.br/api/templates \
-H "Authorization: Bearer SEU_TOKEN_DE_INSTANCIA" \
-H "Content-Type: application/json" \
-d '{
"name": "pedido_confirmado",
"language": "pt_BR",
"category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "TEXT", "text": "Pedido confirmado" },
{
"type": "BODY",
"text": "Olá, {{1}}. Seu pedido {{2}} foi confirmado e será entregue em até {{3}} dias úteis.",
"example": { "body_text": [["Marina", "48213", "5"]] }
},
{ "type": "FOOTER", "text": "Loja Exemplo" },
{
"type": "BUTTONS",
"buttons": [
{ "type": "URL", "text": "Acompanhar pedido", "url": "https://loja.exemplo.com.br/pedidos/{{1}}", "example": ["https://loja.exemplo.com.br/pedidos/48213"] }
]
}
]
}'A resposta traz o id, o status (em geral PENDING) e a categoria. O resultado da revisão chega pelo webhook message_template_status_update, que a Vectalk repassa no mesmo formato da Meta para as URLs registradas (veja o guia de webhooks da API do WhatsApp). Para consultar depois, use GET /api/templates?name=pedido_confirmado.
Regras que evitam erro já na criação:
- O nome aceita só letras minúsculas, números e sublinhado, com até 512 caracteres. Nomes não são únicos: o mesmo nome pode existir em idiomas diferentes, e cada idioma conta como um template.
- A Meta permite criar até 100 templates por hora em cada conta.
- Uma conta pode ter até 250 templates se o portfólio empresarial não for verificado. Com o portfólio verificado e um número com nome de exibição aprovado, o teto sobe para 6.000.
- A Meta não traduz nada. Cada idioma precisa do próprio texto e dos próprios exemplos.
- Cabeçalho de mídia exige, na Meta, um handle obtido pela Resumable Upload API, e a imagem de exemplo também passa pela revisão.
Variáveis: posicionais ou nomeadas
O campo parameter_format define o formato. Sem ele, o padrão é positional.
Posicionais usam {{1}}, {{2}} e assim por diante, em sequência. Os valores de exemplo na criação e os valores reais no envio seguem a ordem em que aparecem no texto.
Nomeadas usam nomes em minúsculas com sublinhado, como {{nome_cliente}}. A ordem dos valores deixa de importar, o que reduz bugs quando o texto muda:
{
"name": "pedido_enviado",
"language": "pt_BR",
"category": "UTILITY",
"parameter_format": "named",
"components": [
{
"type": "BODY",
"text": "Olá, {{nome_cliente}}! Seu pedido {{numero_pedido}} saiu para entrega com o código de rastreio {{rastreio}}. Avisaremos quando for entregue.",
"example": {
"body_text_named_params": [
{ "param_name": "nome_cliente", "example": "Marina" },
{ "param_name": "numero_pedido", "example": "48213" },
{ "param_name": "rastreio", "example": "BR123456789" }
]
}
}
]
}No envio, cada parâmetro nomeado leva parameter_name:
{ "type": "text", "parameter_name": "rastreio", "text": "BR987654321" }Todo parâmetro precisa de valor de exemplo na criação. Sem exemplo, a revisão não tem como avaliar o texto final.
Enviando o template
O envio usa o endpoint de mensagens com type: "template". Pela Vectalk:
curl -X POST https://apis.vectalk.com.br/api/messages \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5584999999999",
"type": "template",
"template": {
"name": "pedido_confirmado",
"language": { "code": "pt_BR" },
"components": [
{ "type": "body", "parameters": [
{ "type": "text", "text": "Marina" },
{ "type": "text", "text": "48213" },
{ "type": "text", "text": "5" }
]},
{ "type": "button", "sub_type": "url", "index": "0", "parameters": [
{ "type": "text", "text": "48213" }
]}
]
}
}'Com token de organização, inclua também o phone_number_id do número remetente no corpo. Os erros mais comuns no envio são estes:
| Código | Significado | O que fazer |
|---|---|---|
132000 | Quantidade de parâmetros diferente da definida no template | Conferir quantos parâmetros cada componente espera |
132001 | Template não existe no idioma informado ou não está aprovado | Conferir nome, código de idioma e status |
132012 | Parâmetros em formato diferente do template | Usar o formato correto (posicional ou nomeado) |
132015 | Template pausado por baixa qualidade | Esperar a pausa ou editar o conteúdo |
132016 | Template desativado após pausas repetidas | Criar um novo template com outro conteúdo |
Por que templates são reprovados
A revisão combina sistemas automáticos e análise manual e leva até 24 horas. Os motivos que a Meta lista como mais comuns são:
- Formato das variáveis: chaves faltando ou trocadas, caracteres especiais como
#,$ou%dentro da variável, numeração fora de sequência ({{1}},{{2}},{{5}}). - Variáveis demais para o tamanho do texto: um corpo curto com muitos parâmetros é reprovado. Aumente o texto fixo ou reduza as variáveis.
- Variável na ponta: o texto não pode começar nem terminar com parâmetro.
- Pedido de dados sensíveis: número completo de cartão, conta bancária ou documento de identidade. Pedir só os últimos dígitos é aceito.
- Conteúdo ameaçador: ameaçar processo ou exposição pública do cliente.
- Violação da Política de Comércio: produtos e serviços proibidos na plataforma.
- Duplicidade: mesmo texto de corpo e rodapé de um template já existente (essa regra não vale para autenticação).
Se discordar da reprovação, você pode editar e reenviar ou abrir um recurso no WhatsApp Manager, com exemplo dos valores. A Meta informa decisão em até 24 horas.
Para editar por API, a Meta permite alterar templates com status APPROVED, REJECTED ou PAUSED. A edição substitui todos os componentes de uma vez, e um template aprovado pode ser editado até 10 vezes em 30 dias ou 1 vez em 24 horas. Na Vectalk, a edição é um POST /api/templates/{templateId} com os novos componentes.
Como evitar que utilidade vire marketing
Esse é o problema mais caro com templates. Pela regra da Meta, um template só é utilidade se cumprir duas condições ao mesmo tempo:
- Ser não promocional, sem intenção persuasiva.
- Ser específico do usuário (ligado a pedido, conta, serviço ou transação dele) ou essencial (segurança, recall, alerta de fraude, mudança de política de privacidade).
Desde 9 de abril de 2025, se você enviar como UTILITY e a Meta concluir que é marketing, o template é aprovado como MARKETING em vez de reprovado. Você só percebe olhando a categoria na resposta ou no webhook.
Depois de aprovado, o template continua sendo avaliado. A Meta roda um processo recorrente que reclassifica utilidades que deveriam ser marketing, com aviso de 1 dia pelo webhook template_category_update e por e-mail. O payload traz a categoria atual em new_category e a correta em correct_category:
{
"field": "template_category_update",
"value": {
"message_template_id": 278077987957091,
"message_template_name": "lembrete_pagamento",
"message_template_language": "pt_BR",
"new_category": "UTILITY",
"correct_category": "MARKETING",
"category_update_timestamp": 1746169200
}
}Na API da Meta, você também pode listar os templates com ?fields=category,correct_category e comparar os dois campos. Quando há divergência, você tem até 60 dias para pedir revisão no Business Support Home.
Veja a diferença na prática:
| Texto | Categoria provável | Por quê |
|---|---|---|
| “Seu pedido {{1}} foi enviado com o rastreio {{2}}. Avisaremos na entrega.” | Utilidade | Específico do pedido, sem promoção |
| “Seu pedido {{1}} foi enviado. Aproveite 10% na próxima compra!” | Marketing | Mistura aviso com oferta |
| “Sua assinatura vence em {{1}}. Renove hoje com desconto.” | Marketing | Tentativa de renovação com incentivo |
| “Sua fatura de {{1}} vence em {{2}} e será cobrada no cartão final {{3}}.” | Utilidade | Alerta de conta sem persuasão |
| “Como foi sua experiência conosco?” | Marketing | Pesquisa genérica, sem atendimento específico |
| “Você falou com nosso suporte sobre o pedido {{1}}. Como foi o atendimento?” | Utilidade | Pesquisa ligada a uma interação específica |
Um checklist antes de enviar como utilidade:
- O texto cita algo do usuário (número do pedido, data, valor, protocolo)?
- Alguma palavra soa como convite para comprar, renovar ou “aproveitar”?
- O botão leva para a página do pedido ou da conta, e não para a vitrine?
- O rodapé está livre de slogan ou chamada comercial?
Insistir em classificar marketing como utilidade tem consequência. A Meta descreve uma escala de restrições para contas que fazem isso de forma recorrente:
| Nível | O que acontece | Duração |
|---|---|---|
| Aviso | Aviso escrito aos administradores; mudanças de utilidade para marketing passam a ser imediatas, sem aviso prévio | Contínuo |
| Limite de taxa | Volume de mensagens de utilidade limitado numa janela de 24 horas; o excedente é rejeitado | Mínimo de 7 dias |
| Restrição de utilidade | Todos os templates de utilidade da conta viram marketing; criação de novos e pedidos de revisão ficam bloqueados | 7 dias (30 na reincidência) |
| Restrição no portfólio | O mesmo, em todas as contas do portfólio | 30 dias |
Essas ações chegam pelo webhook account_update, com violation_type igual a UTILITY_TEMPLATE_ABUSE.
Qualidade e pausa de templates
Cada template aprovado recebe uma nota baseada em uso, feedback e engajamento: GREEN (alta), YELLOW (média), RED (baixa) ou UNKNOWN (ainda sem dados). Um template que chega a RED é pausado automaticamente: 3 horas na primeira vez, 6 horas na segunda e desativado na terceira. Enquanto pausado, a API rejeita os envios sem cobrar e sem contar no limite de mensagens.
Pausar campanhas que dependem do template evita uma fila de erros. A pausa não atinge o número de imediato, mas a Meta avisa que enviar com frequência templates que chegam a baixa qualidade pode acabar afetando o número. O cuidado com volume e público está no artigo sobre disparo em massa pela API oficial.
Perguntas frequentes
Quanto tempo a Meta leva para aprovar um template?
A documentação informa que a decisão sai em até 24 horas. Muitos templates são aprovados antes disso, mas planeje o lançamento contando com o prazo máximo.
Posso enviar um template para qualquer número?
Não. A Meta exige que o destinatário tenha dado consentimento (opt-in) para receber mensagens da sua empresa, e os envios fora da janela contam no limite de mensagens do portfólio.
Posso mudar a categoria de um template aprovado?
Pela API, a categoria de um template aprovado não pode ser editada. Para templates reprovados, você pode editar a categoria e reenviar. Para templates aprovados como marketing que você considera utilidade, a revisão é pedida no WhatsApp Manager.
Um template de utilidade enviado dentro da janela de 24 horas é gratuito?
Não mais. Desde 1º de outubro de 2026, a Meta cobra utilidade enviada dentro da janela de atendimento. A única exceção em que template não é cobrado é a janela de ponto de entrada gratuito, aberta por anúncios de clique para o WhatsApp.
Na Vectalk, o payload de template é diferente do da Meta?
Não. Os corpos de criação e envio são os mesmos da Cloud API. Mudam a URL base (https://apis.vectalk.com.br/api) e o token, que é gerado no painel da Vectalk.
Crie seus templates pela Vectalk
Na Vectalk você cria, lista, edita e envia templates com os mesmos payloads da documentação da Meta e um token para todas as suas contas. A cobrança da Meta passa pela Vectalk: você paga a Vectalk, e a Vectalk paga a Meta, sem cadastrar cartão na Meta. Crie sua conta em apps.vectalk.com.br/register, consulte os endpoints em docs.vectalk.com.br ou fale com o time pela página de contato.
Fontes oficiais consultadas em 25/10/2026: Fundamentos de templates, Categorização de templates, Revisão de templates, Atualizações nas contas do WhatsApp Business.