Variáveis de template no WhatsApp: as regras que reprovam na criação e os seis códigos de erro que derrubam a mensagem na hora do envio
Chave desbalanceada, numeração fora de ordem e texto que termina em variável reprovam o template antes de ele existir. Depois de aprovado, o mesmo campo volta a falhar no disparo com códigos como 132000, quando a quantidade de parâmetros não bate com a do template, e 132012, quando os valores não seguem o formato definido.
Como escrever uma variável de template corretamente?
Uma variável de template do WhatsApp é sempre escrita entre chaves duplas, em um de dois formatos: posicional, como {{1}}, ou nomeado, como {{order_number}}. Se você não declarar o formato na criação, a plataforma assume posicional. Toda variável usada exige um valor de exemplo preenchido na submissão, sem exceção.
Na documentação da WhatsApp Business Platform esse elemento aparece como parâmetro, e no WhatsApp Manager aparece como variável. São a mesma coisa: o trecho do texto que fica em branco no template aprovado e é preenchido na hora do disparo. Este texto usa a documentação oficial de componentes, revisão de template e códigos de erro, espelhada e traduzida internamente pelo AI Hub Brasil em 21 de maio de 2026.
Variável nomeada ou posicional: qual usar?
| Formato | Como se escreve | Regra | Ordem dos exemplos |
|---|---|---|---|
| Nomeado | {{first_name}}, {{order_number}} | Nome único, só letras minúsculas e sublinhado, entre chaves duplas. | Os exemplos podem vir em qualquer ordem. |
| Posicional | {{1}}, {{2}} | Índices numéricos em ordem, começando em 1, entre chaves duplas. | Os exemplos devem seguir a ordem em que os marcadores aparecem no texto. |
A recomendação prática para textos com muitas variáveis é declarar o formato nomeado. Ele elimina a classe de erro mais silenciosa da operação: preencher os valores na ordem errada. Com {{1}} e {{2}}, trocar dois campos gera uma mensagem gramaticalmente perfeita e factualmente errada, que nenhuma validação pega. Com {{order_number}} e {{delivery_date}}, o erro fica visível para quem escreve o disparo.
Onde cada parte do template aceita variável
- Corpo: aceita múltiplos parâmetros. É onde a personalização vive.
- Cabeçalho de texto: aceita no máximo um parâmetro, dentro do limite de 60 caracteres.
- Botão de URL: aceita uma variável, sempre no fim da URL. Não no meio, não no início.
- Rodapé: a base consultada não documenta suporte a variável no rodapé. Trate como texto fixo.
- Templates de autenticação: os parâmetros são limitados a 15 caracteres, e não são permitidos URL, mídia nem emoji no conteúdo ou nos parâmetros.
Por que a variável reprova o template na criação?
A documentação de revisão de template lista cinco falhas de variável que causam reprovação. Todas são verificáveis antes de submeter, com uma leitura atenta do texto.
- Chaves desbalanceadas ou ausentes. O formato correto posicional é
{{1}}, com duas chaves de cada lado. - Caractere especial dentro da variável. Símbolos como
#,$e%não podem estar dentro das chaves. O cifrão vai fora, no texto fixo. - Numeração fora de sequência. A ordem
{{1}},{{2}},{{5}},{{4}}reprova. Os índices precisam ser sequenciais a partir de 1, sem pular e sem inverter. - Variáveis demais para o tamanho do texto. A correção indicada é reduzir o número de variáveis ou aumentar o texto fixo do corpo.
- Parâmetro solto no começo ou no fim. O template não pode abrir nem fechar com uma variável crua. Precisa de texto fixo nas duas pontas.
A regra do parâmetro solto é a que mais pega copy brasileiro. Frases como "Olá, {{1}}" no início ou terminar a mensagem com o link em variável são construções naturais para quem escreve, e ambas reprovam. A correção é banal quando conhecida: basta uma palavra fixa antes ou depois.
Vale lembrar por que a Meta é rígida aqui. Um corpo cujo conteúdo é apenas {{1}} não é só mal formatado: ele é classificado como conteúdo vago e cai automaticamente na categoria marketing, que custa mais que utilidade. Excesso de variável tem, portanto, um efeito de categoria além do efeito de reprovação.
Quais erros de parâmetro só aparecem no envio?
Template aprovado não significa envio garantido. Os valores que você injeta no disparo passam por uma segunda validação, e ela devolve códigos próprios. A regra de ouro da documentação é tratar o erro sempre pelo campo numérico code, nunca pelo título em texto, que a Meta pretende descontinuar.
| Código | O que significa | O que fazer |
|---|---|---|
132000 | A quantidade de valores enviados não bate com a que o template exige. | Enviar exatamente o número de parâmetros do template. |
132005 | Nomeado na referência como texto preenchido longo demais, com a descrição oficial "o texto traduzido é longo demais". | Conferir no WhatsApp Manager se o template foi traduzido e encurtar o texto. |
132012 | Os valores não seguem o formato que o template define. | Formatar os parâmetros conforme a definição do template. |
132018 | Erro de validação nos parâmetros do template. | Revisar e corrigir os parâmetros antes de reenviar. |
131008 | Faltou um campo obrigatório na requisição. | Incluir o parâmetro ausente. |
131009 | Valor de parâmetro inválido. | Corrigir o valor enviado. |
O código 132005 merece atenção de quem trabalha com dados reais. O nome dele na referência de erros é justamente texto preenchido longo demais, e a orientação oficial manda conferir a tradução do template no WhatsApp Manager. A implicação prática, que a documentação não explicita mas decorre do limite de 1024 caracteres do corpo, é que o teste precisa ser feito com o pior caso da sua base: um corpo que cabe folgado com o exemplo "João" fica apertado quando a variável recebe a razão social completa de uma empresa.
Checklist de variável antes de submeter
- Toda variável entre chaves duplas, no formato posicional ou nomeado, sem misturar os dois.
- Variáveis nomeadas com apenas letras minúsculas e sublinhado.
- Variáveis posicionais sequenciais a partir de 1, sem pular nem inverter.
- Nenhum caractere especial dentro das chaves.
- Texto abrindo e fechando com palavra fixa, nunca com variável.
- Número de variáveis proporcional ao tamanho do texto.
- Valor de exemplo preenchido para cada variável, na ordem certa quando o formato for posicional.
- Cabeçalho de texto com no máximo uma variável, e botão de URL com a variável no fim do endereço.
- Teste do texto preenchido com o maior valor real da sua base, para não estourar o limite no envio.
Esse checklist encaixa naturalmente na rotina de quem já organizou o canal. Se a operação ainda é manual, o desenho do fluxo vem antes da peça, e o caminho está no guia de como automatizar o atendimento no WhatsApp.
Leitura crítica
Chama atenção que a maior parte das reprovações de template no WhatsApp não seja sobre o que a mensagem diz, e sim sobre onde as chaves foram colocadas. Isso é, na prática, uma boa notícia: são erros determinísticos, que um validador interno de dez linhas resolve antes de qualquer submissão. Times que perdem ciclos de 24 horas com isso estão pagando com tempo de campanha algo que se resolve com código.
O ponto que a documentação não resolve é a validação de conteúdo do parâmetro no envio. Não existe um mecanismo de tipo que garanta que a variável de data receba uma data, ou que o número do pedido não venha vazio. Uma mensagem com "Seu pedido chega em null" é aprovada pela revisão e entregue pela API sem erro nenhum, porque a falha é de dado, não de formato. A validação desse tipo continua sendo responsabilidade inteira de quem integra.
Por fim, a preferência por variável nomeada não é estética. Ela transfere a checagem de ordem do humano para o código, e é a única mudança de baixo custo que reduz o erro mais caro dessa área: o que passa por todas as validações e chega bonito, correto e falso no celular do cliente.