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

Se você quer disparar uma mensagem para um cliente que ainda não te respondeu hoje, não dá para mandar texto livre. Você precisa usar um template aprovado. Enviar mensagem de template no WhatsApp Business API significa fazer uma chamada à Cloud API referenciando um modelo que a Meta já aprovou, preenchendo as variáveis daquele modelo e informando o número de destino. É isso que libera o envio ativo fora da janela de 24 horas.

Parece simples, e é, quando o template já existe e está aprovado. O que trava a maioria das pessoas não é o envio em si: é template rejeitado, variável no lugar errado ou tentar mandar promoção fora das regras. Vamos pela ordem certa.

Por que template existe (e quando você é obrigado a usar)

O WhatsApp separa dois momentos. Quando o cliente te manda uma mensagem, abre uma janela de 24 horas em que você responde com o que quiser: texto, imagem, botão, o que precisar. Passou das 24 horas sem interação nova, essa liberdade fecha.

A partir daí, para iniciar ou retomar a conversa, só com template aprovado. É a forma que a Meta encontrou de garantir que empresa não sai disparando mensagem para quem não pediu. Então a regra prática é direta: dentro da janela, texto livre; fora dela, template.

Na prática, quase todo caso de uso ativo depende de template. Confirmação de pedido, aviso de entrega, lembrete de consulta, código de verificação, campanha. Tudo isso começa com um modelo pré-aprovado.

Passo 1: criar e aprovar o template antes de qualquer envio

Você não escreve o texto na hora do disparo. O template é cadastrado antes, revisado pela Meta e só depois fica disponível para uso. No cadastro você define três coisas que mudam tudo depois.

A categoria é a primeira. Hoje são três: marketing, utilidade (utility) e autenticação. Marketing cobre promoção e divulgação. Utilidade é para mensagens transacionais que o cliente espera, como status de pedido. Autenticação é só para códigos de verificação. Escolher a categoria errada é o motivo número um de rejeição que a gente vê: um aviso de entrega enviado como marketing, ou uma promoção disfarçada de utilidade.

Depois vem o idioma e o corpo do texto, onde entram as 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 enviado e chega até {{3}}.

Você também pode adicionar cabeçalho (texto, imagem, vídeo ou documento), rodapé e botões (de resposta rápida ou de link/telefone). Cada um desses elementos aparece depois na estrutura da requisição.

A aprovação costuma ser rápida, mas não é instantânea nem garantida. Quando um cliente nos procura com template rejeitado, quase sempre é por texto vago, promoção classificada como utilidade ou variável sem exemplo de preenchimento. Preencher o exemplo de cada variável no cadastro ajuda o revisor a entender o contexto e reduz recusa.

Passo 2: montar a requisição de envio

Com o template aprovado, o envio é uma chamada HTTP POST para o endpoint de mensagens da Cloud API, no formato /{phone-number-id}/messages. Você precisa do ID do número de telefone (phone number ID) e de um token de acesso no cabeçalho de autorização.

O corpo da requisição, em JSON, tem a estrutura básica assim:

{ "from": "123456789012345", "to": "5547999999999", "type": "template", "template": { "name": "confirmacao_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "João Silva" }, { "type": "text", "text": "#4521" } ] } ] } } Você pode ver mais detalhes na documentação da API: documentação da API

Três pontos merecem atenção. O campo to vai com o número no formato internacional, sem sinal de mais e sem espaços.

O name é exatamente o nome que você deu ao template no cadastro. E o language.code precisa bater com o idioma cadastrado: se você criou em pt_BR, mandar pt retorna erro.

Preenchendo as variáveis no components

É aqui que a maioria erra. O array components é onde você entrega os valores das variáveis, na ordem exata em que aparecem no template. Para o corpo com três variáveis do exemplo anterior, fica assim:

"components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Maria" }, { "type": "text", "text": "#4821" }, { "type": "text", "text": "sexta-feira" } ] } ]

A ordem dos parameters corresponde a {{1}}, {{2}} e {{3}}. Inverter a ordem não gera erro técnico, mas manda a informação trocada para o cliente, o que é pior. Se o template tiver cabeçalho com imagem, você adiciona um componente header com o link ou o ID da mídia. Se tiver botão dinâmico de URL, entra um componente button com o índice e o valor.

Enviar sem variáveis

Se o seu template não tem nenhuma variável, texto totalmente fixo, você pode omitir o array components por completo. Basta o name e o language. Muita gente insiste em mandar parâmetros vazios e recebe erro por isso.

Passo 3: interpretar a resposta e os erros

Deu certo, a API devolve um JSON com o id da mensagem (o wamid). Isso não quer dizer que o cliente já leu: significa que a Meta aceitou o envio. Os status de entregue e lido chegam depois pelo webhook, se você tiver configurado.

Quando dá errado, o código de erro no retorno diz muito. Os que mais aparecem no dia a dia:

• Número de parâmetros diferente do template: você mandou dois valores para um template que tem três variáveis, ou vice-versa.
• Template não encontrado: nome digitado errado ou código de idioma que não bate com o cadastro.
• Template pausado ou com qualidade baixa: se muita gente marca aquele modelo como spam, a Meta pode pausar o envio dele.
• Sem opt-in ou fora de política: disparos em massa para quem não deu consentimento derrubam a qualidade do número rápido.

Esse último ponto vale um alerta. Segundo a covercut, BSP oficial do WhatsApp, o que mais derruba a qualidade de um número não é volume alto: é mandar template de marketing para gente que não pediu. A classificação de qualidade (alta, média ou baixa) reage a bloqueios e denúncias, e qualidade baixa reduz seus limites diários de conversas iniciadas.

Opt-in e a janela de 24 horas na prática

Antes de enviar qualquer template ativo, você precisa do consentimento do cliente. Opt-in não é burocracia decorativa: é o que separa uma operação saudável de um número que vive na faixa vermelha. Guarde o registro de onde e quando a pessoa autorizou receber mensagens.

Uma vez enviado o template e o cliente respondendo, abre a janela de 24 horas. Dentro dela você conversa livremente, sem gastar novo template. É por isso que muitos fluxos usam o template só para iniciar o contato e depois seguem com texto livre enquanto a janela estiver aberta.

Sobre custo e o que a covercut faz

Vale entender quem paga o quê. A Meta cobra por conversa, e essa cobrança vai direto para o cartão que o cliente cadastra na conta dele na Meta. A covercut não cobra por mensagem, por conversa nem por template. Nossa mensalidade é fixa e cobre plataforma, conexão do número pelo fluxo oficial (Embedded Signup), com suporte a coexistência, infraestrutura e suporte.

Coexistência, aliás, resolve uma dúvida comum de quem já usa o app WhatsApp Business: você pode conectar esse mesmo número à API oficial sem apagar a conta, sem desinstalar o app e sem perder o histórico. O app no celular e a API funcionam juntos, no mesmo número.

Se você está começando agora, o caminho é este: cadastre o template na categoria certa, aguarde a aprovação, teste o envio para o seu próprio número validando a ordem das variáveis, e só então ligue o disparo no seu sistema. Testar com um número antes de escalar evita a maior parte das dores de cabeça.

Perguntas frequentes

Preciso de template para responder um cliente que acabou de me mandar mensagem?

Não. Quando o cliente inicia a conversa, abre uma janela de 24 horas em que você responde com texto livre, imagem, botões ou o que precisar. O template só é obrigatório para iniciar conversa ou responder depois que essa janela de 24 horas fecha.

Quanto tempo demora para a Meta aprovar um template?

Costuma ser rápido, muitas vezes em poucos minutos ou algumas horas, mas não é garantido nem instantâneo. Textos vagos, categoria errada (mandar promoção como utilidade, por exemplo) e variáveis sem exemplo de preenchimento aumentam a chance de rejeição e atrasam tudo.

Posso mudar o texto de um template já aprovado na hora do envio?

Não. O texto fixo do template não muda no disparo. O que você preenche na requisição são apenas os valores das variáveis ({{1}}, {{2}} e assim por diante). Para alterar o texto fixo, é preciso editar o template e passar por nova revisão da Meta.

Por que meu envio de template retorna erro de número de parâmetros?

Porque a quantidade de valores no array components não bate com a quantidade de variáveis do template. Se o modelo tem três variáveis, você precisa mandar exatamente três parâmetros, na ordem correta. Templates sem variáveis devem ser enviados sem o array de parâmetros.

Enviar templates pela API oficial tem algum custo por mensagem cobrado pela covercut?

Não. A cobrança por conversa é da Meta e vai direto para o cartão que o cliente cadastra na própria conta da Meta. A covercut cobra apenas uma mensalidade fixa pelo serviço e não repassa nem intermedia o valor das mensagens.