Índice
Pontos Principais
- •A sintaxe de variável no WhatsApp usa chaves duplas numeradas em sequência contínua a partir de 1, sem espaços internos e sem pular números.
- •Templates que começam ou terminam com placeholder são reprovados com frequência porque a Meta não consegue avaliar o texto final da mensagem.
- •O erro de parâmetro no disparo quase sempre vem de divergência entre a quantidade de variáveis aprovadas e a quantidade de valores enviados.
- •Campos vazios, quebras de linha e excesso de espaços na base de contatos derrubam envios individuais mesmo com o template já aprovado.
- •Validar a base e fazer um envio de teste antes da campanha evita retrabalho, bloqueios parciais e mensagens com lacunas visíveis para o cliente.
Segundo pesquisas do setor de atendimento digital, como os levantamentos anuais da Opinion Box sobre uso do WhatsApp no Brasil, a grande maioria dos consumidores brasileiros usa o aplicativo diariamente e espera respostas rápidas e personalizadas das empresas. Na prática, isso significa que erros em variáveis de template — mensagens que chegam com {{1}} no lugar do nome do cliente — tendem a derrubar as taxas de resposta e aumentar bloqueios, já que a personalização quebrada é lida como spam.
Resumo
Variáveis são os campos dinâmicos de um template do WhatsApp — os trechos entre chaves duplas, como {{1}}, que a plataforma substitui pelo nome do cliente, número do pedido ou data de entrega no momento do envio. Quando algo está errado nelas, o resultado é sempre um dos dois: o template é reprovado pela Meta antes de existir, ou ele é aprovado e falha na hora do disparo.
A boa notícia é que a lista de causas é curta e repetitiva. Quase todo erro de variáveis template WhatsApp cai em: numeração fora de sequência, variável colada no início ou no fim do texto, exemplo de conteúdo ausente na submissão, quantidade de parâmetros enviados diferente da quantidade declarada, ou conteúdo dinâmico que a Meta interpreta como potencialmente abusivo.
Em uma frase: template reprovado é problema de formato e política, resolvido antes da aprovação; erro no disparo é problema de preenchimento, resolvido no sistema que envia a mensagem. Diagnosticar em qual dos dois lados o problema está economiza horas de tentativa e erro.
O que você vai encontrar neste artigo
- O que são placeholders na WhatsApp Business API e onde eles podem aparecer dentro de um template.
- A sintaxe correta, as regras de ordem e por que o contexto ao redor da variável importa tanto quanto ela.
- Os erros mais comuns que levam a template WhatsApp reprovado pela Meta e como corrigir cada um.
- Boas práticas para escrever templates que passam na primeira submissão e não quebram em produção.
| Sintoma | Onde está o problema | Momento da correção |
|---|---|---|
| Template rejeitado na análise | Formato, exemplos ou política de conteúdo | Antes de submeter novamente |
| Template aprovado, envio falha | Número ou tipo de parâmetros enviados | No sistema de disparo |
| Mensagem chega com campo vazio | Base de contatos com dados faltando | Na higienização da lista |
| Template pausado após envios | Qualidade baixa por feedback dos destinatários | Na estratégia de segmentação |
O que são variáveis (placeholders) em um template do WhatsApp
Um template (ou modelo de mensagem) é um texto pré-aprovado pela Meta que sua empresa pode enviar para clientes mesmo fora da janela de 24 horas de atendimento. Como o texto é fixo e passa por análise, ele precisaria ser genérico — e é aí que entram as variáveis.
Placeholders na WhatsApp Business API são marcadores que reservam um espaço dentro do texto aprovado. A Meta analisa a estrutura da frase uma única vez; a cada disparo, sua plataforma injeta o valor real naquele espaço. Assim, um mesmo template serve para milhares de clientes com informações diferentes.
Exemplo prático: o template aprovado é "Olá, {{1}}! Seu pedido {{2}} foi despachado e chega até {{3}}." No envio, sua plataforma preenche com "Marina", "#48213" e "quinta-feira". O cliente recebe uma mensagem pessoal, mas a Meta aprovou apenas a moldura.
Onde as variáveis podem aparecer
Um template é dividido em componentes, e cada um tem regras próprias quanto ao uso de placeholders. Confundir essas regras é uma das origens mais frequentes de reprovação.
| Componente | Aceita variável? | Observação |
|---|---|---|
| Cabeçalho de texto | Sim, de forma limitada | Espaço bem curto; use com parcimônia |
| Cabeçalho de mídia | Sim (o próprio arquivo) | Imagem, vídeo ou documento definido no disparo |
| Corpo da mensagem | Sim | É onde a maioria dos placeholders vive |
| Rodapé | Não | Texto totalmente estático |
| Botão de URL dinâmica | Sim, no final da URL | O domínio precisa ser fixo e conhecido |
Por que a Meta é rigorosa com placeholders
A revisão do template acontece antes de qualquer envio. Se uma variável for ampla demais, a Meta perde a capacidade de prever o que será entregue ao usuário — e um texto aparentemente inofensivo poderia virar spam ou golpe no disparo real.
- Previsibilidade: a variável deve substituir um dado pontual, não uma frase inteira.
- Rastreabilidade: o texto ao redor precisa deixar claro o propósito da mensagem.
- Experiência do usuário: mensagens quebradas ou com campos vazios geram bloqueios e denúncias, o que derruba a qualidade do número.
Como usar variáveis no template do WhatsApp: sintaxe, ordem e contexto
Quem procura como usar variáveis no template do WhatsApp geralmente quer três respostas: qual símbolo usar, como numerar e onde posicionar. As três importam, mas a terceira é a que mais causa reprovação silenciosa.
1. Sintaxe: chaves duplas, sem espaços
O padrão é chave dupla abrindo, o índice e chave dupla fechando. Nada além disso. Espaços internos, chaves simples, colchetes ou nomes personalizados no formato posicional quebram a leitura do template.
| Escrita | Válida? | Motivo |
|---|---|---|
| {{1}} | Sim | Formato posicional padrão |
| {{ 1 }} | Não | Espaços dentro das chaves |
| {1} | Não | Chave simples não é reconhecida |
| [nome] | Não | Vira texto literal na mensagem |
2. Ordem: sequencial e sem buracos
A numeração precisa começar em 1 e seguir sem pular números. Se o texto tem três variáveis, elas são 1, 2 e 3 — nunca 1, 3 e 4. Isso vale por componente: o cabeçalho e o corpo têm contagens independentes.
O erro clássico aparece na edição: você escreve um template com quatro variáveis, apaga a segunda e submete com 1, 3 e 4. A análise falha imediatamente, e a mensagem de retorno raramente explica isso com clareza.
Dica de revisão: depois de editar qualquer template, leia o texto do começo ao fim contando as variáveis em voz alta. Se a última não corresponder ao total de campos, renumere antes de enviar para análise. Leva trinta segundos e evita um ciclo de reprovação que pode custar dias.
3. Contexto: a variável nunca fica sozinha
Esta é a regra que mais surpreende. Uma variável não pode abrir nem fechar o texto, não pode ficar imediatamente ao lado de outra variável e não pode ser o único conteúdo de um componente. Precisa haver texto fixo suficiente ao redor para que a Meta entenda a mensagem.
- Evite: "{{1}}, seu pedido chegou." — começa com variável.
- Prefira: "Olá, {{1}}! Seu pedido chegou." — texto antes e depois.
- Evite: "Entrega em {{1}} {{2}}" — variáveis adjacentes e final aberto.
- Prefira: "Entrega prevista para {{1}} na cidade de {{2}}. Qualquer dúvida, é só responder."
4. Exemplos de preenchimento na submissão
Ao cadastrar o template, você precisa informar um exemplo de valor para cada variável. Não é burocracia: é o que o revisor usa para simular a mensagem final. Exemplos genéricos como "teste" ou "xxx" aumentam a chance de reprovação.
Use amostras realistas e coerentes com o campo — um nome próprio para o nome, um código no formato que você realmente usa para o pedido, uma data plausível para a entrega. Quanto mais próximo do envio real, melhor a leitura da análise.
Atenção ao disparo: a quantidade de parâmetros enviados precisa bater exatamente com a quantidade declarada no template. Enviar dois valores para um template de três variáveis gera erro na API e a mensagem simplesmente não sai — mesmo com o template aprovado.
Os 7 erros mais comuns que reprovam ou quebram variáveis (com exemplos de antes e depois)
A maioria dos casos de variáveis template WhatsApp erro não vem de regras obscuras da Meta. Vem de descuidos de escrita que se repetem em quase todas as empresas: numeração fora de ordem, exemplo faltando, texto vago demais ou placeholder colado na borda da mensagem.
Abaixo estão os sete erros que mais aparecem em reprovações e em falhas de envio. Cada um vem com o "antes" (o que quebra) e o "depois" (o que passa), para você comparar direto com os templates que já tem cadastrados.
| Erro | Antes (quebra) | Depois (funciona) |
|---|---|---|
| 1. Numeração fora de sequência | Olá {{1}}, seu pedido {{3}} saiu para entrega. | Olá {{1}}, seu pedido {{2}} saiu para entrega. |
| 2. Variável repetida com número diferente | Oi {{1}}! Confirmamos, {{2}}, sua reserva. (mesmo nome duas vezes) | Oi {{1}}! Confirmamos, {{1}}, sua reserva. |
| 3. Chaves malformadas | Olá {1} / {{ 1 }} / {{1} | Olá {{1}} (duas chaves, sem espaço interno) |
| 4. Exemplo genérico ou ausente | Exemplo de {{1}}: "variavel1" ou campo em branco | Exemplo de {{1}}: "Mariana" |
| 5. Variáveis coladas uma na outra | Seu pedido {{1}}{{2}} foi aprovado. | Seu pedido {{1}} no valor de {{2}} foi aprovado. |
| 6. Mensagem quase toda variável | {{1}} {{2}} {{3}} {{4}} | Olá {{1}}, sua consulta em {{2}} está confirmada para {{3}}. |
| 7. Quantidade de valores diferente do template | Template com 3 variáveis, envio com 2 valores | Um valor para cada variável, sempre na mesma ordem |
Erros de aprovação x erros de envio
Vale separar os dois grupos. Os erros 1 a 6 costumam aparecer na revisão: o template é recusado e você recebe um status de rejeição antes de enviar qualquer mensagem. É o clássico template WhatsApp reprovado Meta.
Já o erro 7 é diferente e mais perigoso: o template foi aprovado, mas a chamada de envio manda menos (ou mais) parâmetros do que o corpo espera. A API rejeita a mensagem, e a campanha sai pela metade sem ninguém perceber na hora.
Dica prática: antes de submeter, leia o template substituindo mentalmente cada placeholder pelo pior valor possível — nome em branco, produto com 60 caracteres, data mal formatada. Se a frase virar algo confuso ou sem sentido, o revisor também vai enxergar isso.
Variável no início ou no fim do template: por que a Meta reprova
Esse é o motivo de reprovação que mais confunde quem está aprendendo como usar variáveis no template do WhatsApp. O texto parece perfeito, o exemplo está preenchido, e mesmo assim a Meta devolve o template negado.
A regra é simples: o corpo da mensagem não pode começar nem terminar com um placeholder. Também não pode ter dois placeholders adjacentes sem texto fixo entre eles.
- Reprovado: "{{1}}, sua entrega chega hoje." — começa com variável.
- Reprovado: "Sua entrega chega em {{1}}" — termina com variável.
- Reprovado: "Pedido {{1}} {{2}} confirmado." — variáveis adjacentes.
- Aprovado: "Olá {{1}}, sua entrega chega em {{2}}. Qualquer dúvida, é só responder aqui."
A lógica por trás da regra
A revisão da Meta precisa entender o significado da mensagem sem ver os dados reais. Quando a variável ocupa a borda do texto, o revisor perde o contexto: não dá para saber se ali entra um nome, um link, um cupom ou uma frase promocional inteira.
Existe também um motivo de segurança. Placeholders soltos nas extremidades são o caminho mais fácil para transformar um template utilitário aprovado em mensagem promocional ou fraudulenta depois da aprovação — basta injetar o texto na hora do envio.
Correção em 5 segundos: se o template começa com variável, coloque uma saudação antes ("Olá", "Oi", "Bom dia"). Se termina com variável, acrescente uma frase de fechamento ("Qualquer dúvida, responda esta mensagem." ou "Obrigado por comprar com a gente!"). Nos dois casos, o conteúdo dinâmico continua o mesmo.
E nos outros componentes?
O cabeçalho de texto aceita no máximo uma variável e segue lógica parecida: um cabeçalho formado só pelo placeholder tende a ser recusado por falta de contexto. O rodapé não aceita variável nenhuma — se você precisa de conteúdo dinâmico ali, ele tem que ir para o corpo.
Nos botões de URL, a variável só pode aparecer no final do endereço, como sufixo de um domínio fixo já declarado. Isso impede que o link inteiro seja trocado depois da aprovação.
Caracteres e conteúdos proibidos dentro das variáveis
Mesmo com o template aprovado, o valor que você injeta em cada placeholder WhatsApp Business API tem restrições próprias. Quando o dado vem sujo de uma planilha ou de um sistema externo, a API recusa a mensagem e a campanha registra falha.
| Conteúdo no valor | O que acontece | Como resolver |
|---|---|---|
| Quebra de linha dentro da variável | Envio rejeitado | Trocar por espaço ou vírgula antes de enviar |
| Tabulação e espaços múltiplos | Envio rejeitado ou texto deformado | Normalizar espaços na importação |
| Valor vazio ou só com espaço | Erro de parâmetro inválido | Definir valor padrão (ex.: "cliente") |
| Chaves duplas no próprio dado | Conflito de interpretação | Limpar o campo na origem |
| Texto muito longo | Estoura o limite do corpo | Truncar o campo com limite fixo |
Conteúdo que a política não permite
Além dos caracteres, existe o problema do uso indevido. Injetar frases promocionais completas, links não declarados ou blocos inteiros de texto dentro de um placeholder é considerado desvio de finalidade pelas políticas do WhatsApp Business.
O risco não é só a mensagem falhar. Reclamações e bloqueios de usuários derrubam a qualidade do número, e templates com histórico ruim podem ser pausados ou desativados pela própria Meta.
- Não use variável para inserir oferta em template utilitário.
- Não use variável para trocar o domínio de um link.
- Não use variável para substituir parágrafos inteiros da mensagem.
- Não injete dados sensíveis desnecessários, como documentos completos.
Boa prática: trate a variável como um campo curto e previsível — nome, número de pedido, data, valor. Se o conteúdo muda o sentido da mensagem, ele não deveria ser variável: crie um segundo template. Ao disparar campanhas pelo Winchat, revise a base importada antes do envio para garantir que cada coluna traga o dado limpo e no formato certo.
Como validar placeholders em escala antes de disparar a campanha
Aprovar o template é apenas metade do caminho. O outro erro clássico acontece no disparo: a Meta aprova a estrutura, mas o envio falha porque os valores enviados não batem com o número de variáveis declaradas. É aí que a maior parte dos erros de variáveis em template do WhatsApp aparece — não na aprovação, mas no volume.
Validar em escala significa checar a base inteira antes do primeiro envio, não descobrir o problema depois de mil mensagens rejeitadas. A lógica é simples: cada contato precisa ter um valor preenchido, no formato certo, para cada placeholder do template.
Regra prática: se o template tem {{1}} e {{2}}, o disparo precisa enviar exatamente dois parâmetros — nem um a mais, nem um a menos. A API não completa lacunas nem ignora sobras.
Limpe a base antes de mapear as variáveis
A maioria dos erros de placeholders no WhatsApp Business API nasce em planilha suja. Campos vazios, nomes em caixa alta, espaços duplos, quebras de linha coladas do Excel e valores com caracteres invisíveis viram falha de envio ou mensagem constrangedora para o cliente.
- Células vazias: filtre a coluna e decida — remover o contato ou usar um valor padrão como "cliente".
- Quebras de linha e tabulações: proibidas dentro de variáveis; substitua por espaço simples.
- Espaços no início e no fim: geram texto com espaçamento duplo no corpo da mensagem.
- Capitalização: "MARIA DA SILVA" vira uma abordagem agressiva; normalize para "Maria".
- Formato de número e data: padronize antes, nunca deixe para o momento do disparo.
Teste em três camadas antes do volume
Quem entende como usar variáveis no template do WhatsApp com segurança nunca vai direto da aprovação para a base completa. O caminho é escalonado: teste interno, amostra pequena e só então o disparo cheio.
| Camada | Público | O que você descobre |
|---|---|---|
| 1. Teste interno | 2 a 3 números da própria equipe | Erro de contagem de parâmetros, quebra de layout, link errado |
| 2. Amostra piloto | 20 a 50 contatos reais variados | Campos vazios na base, nomes estranhos, valores fora do padrão |
| 3. Disparo completo | Base segmentada inteira | Comportamento de entrega, taxa de resposta, bloqueios |
Leia o retorno da API em vez de adivinhar
Quando o envio falha, a API do WhatsApp Business devolve um código e uma descrição do problema. Erros relacionados a parâmetros costumam apontar diretamente para incompatibilidade entre o número de variáveis do template e o número de valores enviados no corpo da requisição.
Em plataformas de campanha como o Winchat, esse mapeamento acontece na interface: você associa cada placeholder a uma coluna da base e visualiza a prévia da mensagem já preenchida antes de agendar o disparo, o que elimina boa parte da chance de erro manual em volume.
Dica de processo: guarde uma versão congelada da planilha usada em cada campanha. Quando aparecer uma mensagem esquisita no histórico de um cliente, você consegue rastrear exatamente qual valor foi enviado naquele placeholder.
Checklist final antes de enviar o template para aprovação
Cada reprovação custa tempo e, dependendo do histórico da conta, aumenta o atrito com a moderação da Meta. Revisar cinco minutos antes de submeter evita dias de espera para reenviar um template corrigido.
Use a lista abaixo como último filtro. Se qualquer item ficar sem resposta clara, ajuste antes de clicar em enviar — é a diferença entre aprovação em poucas horas e um template do WhatsApp reprovado pela Meta.
Estrutura das variáveis
- A numeração é sequencial e começa em
{{1}}, sem pular números. - Nenhuma variável abre ou fecha o corpo da mensagem.
- Não existem duas variáveis coladas uma na outra sem texto entre elas.
- As chaves estão duplas e fechadas corretamente em todas as ocorrências.
- Não há espaço dentro das chaves.
Conteúdo e categoria
| Item de verificação | Aprovado se | Risco se ignorado |
|---|---|---|
| Categoria escolhida | Marketing, utilidade ou autenticação coerente com o texto | Reprovação ou reclassificação automática |
| Exemplos preenchidos | Cada variável tem um exemplo real e plausível | Reprovação por falta de contexto para o revisor |
| Ortografia e acentuação | Texto revisado, sem erros e sem caixa alta excessiva | Percepção de spam pela moderação |
| Links e botões | URLs válidas, do próprio domínio, testadas no navegador | Reprovação por link quebrado ou encurtador suspeito |
| Nome do template | Minúsculas com underline, descritivo e versionado | Confusão interna e disparo do template errado |
Simulação final
Antes de submeter, escreva a mensagem completa como ela vai chegar ao cliente, substituindo mentalmente cada placeholder por um valor real. Leia em voz alta. Se soar artificial, com espaçamento estranho ou pontuação duplicada, o problema está na estrutura das variáveis, não no conteúdo.
Faça a mesma leitura com o pior caso possível da sua base: o nome mais longo, o valor mais alto, a data mais distante. Templates que só funcionam com dados perfeitos falham no primeiro contato fora do padrão.
Último passo: documente cada template aprovado em um arquivo compartilhado com nome, categoria, número de variáveis e o que cada uma representa. Sem esse registro, a equipe passa a errar o mapeamento de placeholders a cada nova campanha — e o ciclo de erros recomeça.