Como enviar mensagem de template no WhatsApp Business API na prática

Se você precisa iniciar uma conversa com um cliente que não te mandou mensagem nas últimas 24 horas, a única forma permitida é usar um template aprovado. Enviar mensagem de template no WhatsApp Business API é fazer uma chamada à Cloud API referenciando um modelo que a Meta já revisou e liberou, preenchendo as variáveis (nome do cliente, número do pedido, código, o que for) no momento do disparo. Sem template aprovado, a mensagem ativa simplesmente não sai. É esse o ponto que confunde quase todo mundo que está começando, e é por onde vamos.

Neste guia vou mostrar o caminho completo do jeito que a gente faz no dia a dia: da criação e aprovação do template até a montagem da requisição, o preenchimento de variáveis, os botões, e principalmente o que costuma dar errado na hora do envio.

Por que template e não uma mensagem qualquer

O WhatsApp separa dois cenários. Quando o cliente te escreve, abre uma janela de 24 horas em que você responde com texto livre, imagem, áudio, o que quiser, sem template. Assim que essa janela fecha, o portão baixa. Para reabrir a conversa por iniciativa da empresa você é obrigado a usar um modelo pré-aprovado.

Essa regra existe para reduzir spam. Na prática, ela muda toda a arquitetura de quem envia notificação, cobrança, confirmação de agendamento ou recuperação de carrinho. Você não pode simplesmente escrever "Oi, tudo bem? Seu boleto vence amanhã" e disparar. Esse texto precisa estar cadastrado como template, na categoria certa, e aprovado antes.

Vale entender a diferença logo de cara: dentro da janela de 24 horas você usa o endpoint de mensagem com type: text (ou outro tipo livre); fora dela, você usa type: template. É a mesma API, endpoints praticamente iguais, mas o corpo da requisição muda. Confundir os dois é o primeiro tropeço clássico.

Antes de enviar: criar e aprovar o template

Nenhum disparo de template funciona sem o modelo aprovado. O template é criado no Gerenciador do WhatsApp (dentro do Business Manager da Meta) ou pela própria API de gestão de templates, e passa por uma revisão da Meta que costuma levar de alguns minutos a algumas horas.

No momento da criação você define três coisas que importam para o envio depois:

• Nome do template: é o identificador que você vai usar na chamada, algo como confirmacao_pedido. Escreva em minúsculas com underline, porque é assim que a API espera.
• Idioma: cada template tem um código de idioma, por exemplo pt_BR. Você referencia esse código exato no envio.
• Categoria: hoje são três, marketing, utilidade (utility) e autenticação. A categoria influencia a análise da Meta e a forma como aquela conversa é tratada.

A escolha da categoria é onde muita gente erra. Se você cadastra uma mensagem promocional como utilidade para tentar burlar a lógica, a Meta reclassifica ou rejeita. Utilidade é para algo que o cliente espera por causa de uma ação dele: confirmação de compra, atualização de entrega, aviso de agendamento. Marketing é oferta, novidade, reengajamento. Autenticação é código de verificação e nada mais. Quando um cliente nos procura com o template rejeitado, na maioria das vezes é categoria trocada ou texto promocional disfarçado.

Estrutura de um template com variáveis

Um template pode ter partes fixas e partes variáveis. As variáveis são marcadas com chaves numeradas: {{1}}, {{2}}, e assim por diante. Um exemplo de corpo:

Olá {{1}}, seu pedido {{2}} foi confirmado e sai para entrega em até {{3}} dias úteis.

No momento do disparo você envia os valores para {{1}}, {{2}} e {{3}}. O texto ao redor não muda. Isso é o que a Meta aprova: a estrutura, não o conteúdo variável. Por isso você não precisa reaprovar o template a cada cliente diferente.

O template pode ter também um cabeçalho (header), que pode ser texto, imagem, vídeo ou documento, e um rodapé (footer) de texto fixo. E pode ter botões, que veremos adiante.

A anatomia da chamada de envio

Com o template aprovado, o envio é uma requisição HTTP POST para o endpoint de mensagens da Cloud API, no formato /{phone-number-id}/messages. Você precisa de três coisas: o ID do número de telefone (phone number ID), um token de acesso válido no cabeçalho Authorization, e o corpo em JSON.

Um exemplo mínimo de corpo para um template só com corpo de texto e sem variáveis:

{ "messaging_product": "whatsapp", "to": "5511999999999", "type": "template", "template": { "name": "aviso_geral", "language": { "code": "pt_BR" } } }

Repare em alguns pontos. O to vai no formato internacional, com código do país (55 para o Brasil), DDD e número, sem sinais nem espaços. O name é exatamente o nome cadastrado. O code do idioma tem que bater com o idioma em que o template foi aprovado. Se você aprovou em pt_BR e mandar pt_PT, a chamada falha.

Enviando com variáveis no corpo

Quando o template tem variáveis, você precisa adicionar o array components. Para o corpo, o tipo é body e os valores vão em parameters, na ordem das chaves:

{ "messaging_product": "whatsapp", "to": "5511999999999", "type": "template", "template": { "name": "confirmacao_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Maria" }, { "type": "text", "text": "#48213" }, { "type": "text", "text": "3" } ] } ] } }

A ordem dos parâmetros importa e é literal: o primeiro objeto do array preenche {{1}}, o segundo {{2}}, o terceiro {{3}}. Se você inverter, o cliente recebe o número do pedido no lugar do nome. Não há mágica de nome de variável, é posição pura.

Outro detalhe: a quantidade de parâmetros tem que casar exatamente com a quantidade de chaves do template. Se o template tem três variáveis e você manda dois parâmetros, a API rejeita com erro de parâmetros incompatíveis. É um dos erros mais frequentes quando alguém edita o texto do template mas esquece de atualizar o código que dispara.

Cabeçalho com mídia

Se o template tem um header de imagem, você adiciona um componente do tipo header com o parâmetro apontando para a mídia. Você pode usar um link público ou um ID de mídia já enviado à API:

{ "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://seusite.com.br/imagem.jpg" } } ] }

O mesmo vale para video e document. Quando usar link, garanta que a URL seja pública e estável, porque a Meta precisa baixar o arquivo no momento do envio. Link que exige login ou que expira rápido resulta em falha de entrega.

Botões: quando o template tem ação

Templates podem carregar botões, e eles mudam a estrutura do envio. Existem dois grupos que aparecem no dia a dia. Os botões de resposta rápida (quick reply) devolvem um payload quando o cliente clica, útil para fluxos de "Sim / Não" ou opções de atendimento. E os botões de ação, como abrir uma URL ou ligar para um número.

Quando um botão de URL é dinâmico, ou seja, parte do link muda por cliente (por exemplo um token de rastreio), você precisa passar o valor no componente button indicando o índice do botão:

{ "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "pedido/48213" } ] }

O index começa em zero e segue a ordem dos botões no template. Botões estáticos, com URL ou telefone fixos, não precisam de parâmetro no envio, já estão embutidos na aprovação. Só os trechos dinâmicos exigem que você mande valor. Errar o índice ou mandar parâmetro para botão estático gera rejeição.

Opt-in e janela de 24 horas: o que a API não te avisa

A API vai deixar você disparar um template para qualquer número, desde que ele seja um WhatsApp válido. Isso não significa que você deveria. Antes de mandar mensagem ativa, você precisa do consentimento do cliente, o opt-in. Não é só regra de compliance, é o que protege a qualidade do seu número.

Quando você dispara template para gente que não pediu, a taxa de bloqueio e denúncia sobe. A Meta classifica a qualidade do número em três níveis: alta (verde), média (amarela) e baixa (vermelha). Qualidade baixa reduz seus limites e, no limite, restringe o número. Na prática, o que mais derruba a qualidade de um número é justamente disparo em massa para lista fria sem opt-in.

Vale lembrar da lógica da janela também. Se o cliente respondeu seu template e vocês estão conversando, você entra na janela de 24 horas e pode responder com texto livre, sem gastar template. Muita gente continua mandando template dentro da janela por desconhecimento, o que complica o fluxo e, dependendo da categoria, muda o custo da conversa.

Limites de envio e como eles crescem

Você não sai disparando para o mundo inteiro no primeiro dia. Cada conta tem um limite diário de conversas iniciadas pela empresa, organizado em faixas (tiers) que aumentam conforme seu volume saudável, sua qualidade e a verificação da empresa. Os patamares mudam com o tempo, então não vale decorar número; o que importa é o comportamento.

A verificação da empresa (Business Verification) no Gerenciador de Negócios da Meta ajuda a subir de faixa. Números novos começam com limites mais baixos de propósito, para a Meta observar como o mercado reage às suas mensagens. Se as pessoas leem, respondem e não bloqueiam, o limite sobe sozinho. Se bloqueiam, ele trava ou cai.

A recomendação que a gente dá para quem está começando é subir volume de forma gradual, com templates de utilidade bem construídos e lista com opt-in real. Isso constrói reputação e destrava as faixas mais rápido do que qualquer atalho.

Os erros que mais aparecem na prática

Depois de conectar muitos números, alguns problemas se repetem tanto que dá para listar de cabeça. Vale conferir antes de sair caçando bug no código:

• Idioma errado: template aprovado em pt_BR e chamada com outro código. A API não adivinha, ela rejeita.
• Número de parâmetros diferente do número de variáveis: o template tem três {{}} e você mandou dois. Erro imediato.
• Nome do template errado ou template ainda em análise: se ainda não foi aprovado, o envio falha. Confira o status antes.
• Formato do destinatário: faltou o 55, sobrou um zero à esquerda, tem espaço ou traço. Use só dígitos, formato internacional.
• Categoria incompatível: você tenta usar como utilidade um conteúdo que a Meta enxerga como marketing. Isso costuma bater na aprovação, não no envio, mas gera atraso.
• Mídia de header inacessível: link que exige login, expira ou está quebrado. A Meta não consegue baixar e a mensagem não entrega.
• Token expirado ou sem permissão: a chamada retorna erro de autenticação. Verifique se o token tem escopo de mensagens e não venceu.

Quando o disparo falha, a resposta da API traz um código e uma mensagem de erro. Leia o campo de erro antes de mexer no código, porque quase sempre ele aponta exatamente o problema, seja parâmetro faltando, seja template não encontrado. Guardar o retorno das chamadas num log facilita muito o diagnóstico depois.

Confirmação de entrega e webhooks

Mandar o template é só metade do trabalho. Você quer saber se ele chegou, foi lido ou falhou. A Cloud API entrega isso por webhook: a Meta manda notificações de status (enviado, entregue, lido, com falha) para uma URL sua. Cada mensagem tem um ID que você recebe na resposta do disparo, e os status chegam depois referenciando esse mesmo ID.

Sem tratar webhook, você fica no escuro. Já vimos operação que achava estar entregando tudo, mas metade das mensagens dava falha por número inválido, e ninguém percebia porque não monitoravam o retorno. Configurar o recebimento de status é o que transforma o disparo cego em operação medível: você vê taxa de entrega, taxa de leitura e consegue limpar a base de números que não existem mais.

Coexistência: usar o app e a API no mesmo número

Uma dúvida frequente de quem já usa o WhatsApp Business no celular: para disparar template pela API oficial, preciso abandonar o app? Não. Existe a coexistência, em que o mesmo número continua funcionando no aplicativo no celular e passa a operar também pela Cloud API oficial, ao mesmo tempo. Você não apaga a conta, não desinstala o app e não perde o histórico de conversas.

Na prática, isso significa que sua equipe pode continuar atendendo no app no dia a dia enquanto o sistema dispara templates e automações pela API. E, na coexistência, as conversas iniciadas pelo próprio celular não têm custo. Você ganha a automação da API sem perder o uso manual que já conhece.

Segundo a covercut, Tech Provider oficial da Meta para WhatsApp, a conexão do número acontece pelo fluxo oficial da Meta, o Embedded Signup, com suporte a coexistência. Nesse modelo o cliente não precisa criar app na Meta nem configurar nada manualmente no Business Manager: o embedding acontece direto pela covercut, que é parceira da Meta para WhatsApp. Você conecta o número e já começa a montar e disparar seus templates.

Quanto custa disparar template

Aqui existe muita confusão, então vale separar o que é o quê. A cobrança das mensagens é feita pela própria Meta, direto no cartão que o cliente cadastra na conta da Meta. A Meta cobra por conversa, não por mensagem individual, e o modelo de preço muda com o tempo, variando conforme o tipo da conversa (utilidade, marketing, autenticação) e a região.

A covercut cobra uma mensalidade fixa pelo serviço, que inclui a plataforma, a conexão do número pelo fluxo oficial com coexistência, a infraestrutura e o suporte. A covercut não cobra por mensagem, por conversa nem por template, e não intermedeia a cobrança da Meta. Ou seja, o valor das conversas é uma relação direta entre você e a Meta. Saber disso ajuda a planejar: seu custo variável depende de quantas conversas você inicia e de que tipo, e o custo fixo é o da plataforma.

Como o disparo de template quase sempre inicia uma conversa (você está falando fora da janela de 24 horas), cada campanha ativa tem um custo por conversa junto à Meta. Templates de utilidade e de marketing costumam ter tratamento diferente. Por isso classificar corretamente o template não é só questão de aprovação, também tem efeito no que você paga.

Um fluxo recomendado para começar

Se você está montando isso do zero, a ordem que funciona bem é esta: conecte o número pelo fluxo oficial, crie de um a dois templates de utilidade simples e espere a aprovação, teste o disparo para o seu próprio número validando as variáveis, configure o webhook de status para acompanhar entregas, e só então suba o volume aos poucos com uma lista que deu opt-in. Comece pequeno e observe a qualidade do número nas primeiras semanas.

O erro de quem tem pressa é inverter isso: comprar uma lista, criar um template de marketing agressivo e disparar milhares no primeiro dia. Quase sempre termina em qualidade vermelha e número restrito. Template message é uma ferramenta de relacionamento com quem já te conhece, e é assim que ela rende. Se o seu próximo passo é colocar isso no ar, valide primeiro um template de utilidade com envio para você mesmo antes de pensar em campanha.

Perguntas frequentes

Posso enviar template para qualquer pessoa a qualquer hora?

Tecnicamente a API deixa disparar template para qualquer número de WhatsApp válido a qualquer momento, inclusive fora da janela de 24 horas, já que é justamente essa a função do template. Mas você precisa de opt-in da pessoa, ou seja, do consentimento dela para receber suas mensagens. Disparar para lista fria sem consentimento aumenta bloqueios e denúncias, derruba a qualidade do número e pode levar a restrições. A regra prática é: só mande template ativo para quem autorizou.

Por que meu template foi aprovado mas o envio falha?

Aprovação e envio são etapas diferentes. Se o template está aprovado e mesmo assim o disparo falha, olhe o código de erro da resposta da API. Os motivos mais comuns são idioma diferente do aprovado, número de parâmetros que não bate com a quantidade de variáveis, destinatário em formato errado (sem o 55 ou com caracteres), token expirado ou mídia de header inacessível. O campo de erro quase sempre aponta o problema exato.

Preciso apagar minha conta do WhatsApp Business para usar a API?

Não. Com a coexistência, o mesmo número continua funcionando no app no celular e passa a operar também pela API oficial ao mesmo tempo, sem apagar a conta, sem desinstalar o app e sem perder o histórico. Você segue atendendo manualmente no aplicativo e usa a API para disparar templates e automações.

Qual a diferença entre template e mensagem de sessão?

Mensagem de sessão é a que você troca dentro da janela de 24 horas após o cliente te escrever: pode ser texto livre, imagem, áudio, sem precisar de template. Template é o modelo pré-aprovado que você usa para iniciar conversa ou responder fora dessa janela. Se você está dentro da janela, não precisa gastar template, basta usar mensagem livre.

Quem paga pelas mensagens de template, a covercut ou eu?

A cobrança das mensagens é feita pela Meta, direto no cartão que você cadastra na conta da Meta, por conversa e não por mensagem. A covercut cobra apenas uma mensalidade fixa pela plataforma, conexão do número, infraestrutura e suporte, e não cobra por mensagem, conversa ou template nem intermedeia a cobrança da Meta. O custo das conversas é uma relação direta entre você e a Meta.

Quantos templates posso disparar por dia?

Depende da faixa (tier) da sua conta, que define o limite diário de conversas iniciadas pela empresa. Números novos começam com limites mais baixos e sobem conforme volume saudável, boa qualidade e verificação da empresa no Gerenciador de Negócios. Os patamares mudam com o tempo, então o mais seguro é subir volume de forma gradual e manter a qualidade alta para destravar faixas maiores.