Como usar variáveis em templates WhatsApp

Em vez de disparar a mesma mensagem genérica para todos os contatos, você mapeia campos do contato (nome, empresa, cargo) para os espaços dinâmicos (#{{1}}, #{{2}}, #{{3}}) definidos no template aprovado pela Meta.

Cada destinatário recebe uma mensagem que parece escrita especificamente para ele, mesmo em campanhas com centenas de contatos.

Disponível em: todos os planos.

Quem pode fazer: qualquer usuário com acesso ao módulo Campanhas.

Módulo: Menu lateral > Campanhas

O que você precisa antes de começar

Ao menos uma inbox WhatsApp conectada na plataforma
Ao menos um template WhatsApp aprovado pela Meta associado à inbox que será utilizada
O template contém variáveis do tipo texto (#{{1}}, #{{2}}, etc.)
Os contatos da audiência possuem os campos que serão mapeados preenchidos
Acesso ao módulo Campanhas na navegação lateral

Configurar variáveis em uma etapa da campanha

O mapeamento de variáveis acontece no Passo 3 - Sequência de mensagens da criação de campanha. Cada etapa da sequência tem seu próprio template e mapeamento independente.

Na barra de navegação lateral, clique em Campanhas
Clique em Nova campanha (ou abra uma campanha existente em status Rascunho)
Preencha o nome, selecione o canal WhatsApp Business e configure a audiência nos passos anteriores
No Passo 3, clique em Adicionar Etapa
No campo Conexão, selecione a inbox (remetente) pelo dropdown
Em Tipo de envio, selecione Template
No campo de conteúdo, clique em Selecionar template - o dropdown exibirá apenas templates aprovados filtrados pela inbox escolhida
Selecione o template desejado. O sistema exibirá as variáveis identificadas (ex: #{{1}}, #{{2}})
Para cada variável, escolha o campo do contato correspondente no dropdown
Observe o preview lateral sendo atualizado em tempo real com dados de um contato real da audiência

⚠️ Importante: O botão Lançar campanha permanece bloqueado enquanto existir pelo menos uma variável sem campo de contato associado em qualquer etapa da sequência.

Como saber se deu certo

✓ A sidebar direita exibe a mensagem com dados reais do contato - os valores das variáveis aparecem substituídos

✓ O card da etapa na listagem exibe o nome do template selecionado

✓ Não há avisos de variáveis sem valor no preview

Verificar o mapeamento pelo preview

O preview lateral usa dados reais de contatos da audiência, não dados fictícios. Isso permite verificar exatamente como a mensagem chegará para cada prospect antes do lançamento.

Na listagem de etapas, clique na etapa que deseja verificar - o preview lateral atualiza automaticamente
Use as setas (anterior / próximo) no preview para navegar entre diferentes contatos da audiência
Verifique se todas as variáveis estão preenchidas com valores corretos para cada contato
Se alguma variável aparecer sem valor, o sistema exibe um aviso de mapeamento incompleto, corrija antes de lançar

💡 Dica: Revise o preview com pelo menos 5 contatos diferentes antes de lançar.

Campos disponíveis para mapeamento

Campos fixos do contato

Campo	Exemplo de uso no template
Nome	"Olá, `{{var_contact_name}}`! Tudo bem?" → "Olá, João! Tudo bem?"
E-mail	"Enviei um material para `#{{1}}`"
Telefone	Raramente usado - o envio já vai para o número do contato
País	"Vi que você está em `#{{1}}`..."

Campos customizados

Tanto campos com contexto Contato quanto campos com contexto Misto (contato E/OU da conversa) são exibidos no editor de mensagens da campanha:

Exemplo de campo	Exemplo de uso
Empresa	"Vi que você trabalha na `#{{1}}`..."
Cargo	"Como `#{{1}}`, você deve lidar com..."
Segmento	"Atendemos muitas empresas do setor de `#{{1}}`..."
Cidade	"Ótimo estar falando com alguém de `#{{1}}`!"

Limites e regras

Regra	Valor
Número de variáveis por template	Definido pela Meta na criação do template
Limite de caracteres por variável	1.024 caracteres por componente (limite da Meta)
Tipos de variável suportados	Apenas variáveis do tipo texto (`#{{n}}`)
Origem dos dados	Apenas campos do contato, não é possível inserir texto livre
Templates disponíveis	Apenas templates com status aprovado pela Meta
Imutabilidade após ativação	Mapeamento não pode ser alterado após a campanha entrar em status Ativa

Erros comuns e soluções

Problema	Causa provável	Solução
Dropdown de templates vazio	Nenhum template aprovado existe para a inbox selecionada	Verifique o status dos templates na Meta. Selecione a inbox correta primeiro
Variável aparece em branco no preview	O contato usado no preview não tem o campo mapeado preenchido	Navegue para outros contatos no preview. Filtre a audiência para incluir apenas contatos com o campo preenchido
Template desselecionado após trocar inbox	O template selecionado não pertence à nova inbox	Defina a inbox antes de selecionar o template
Envio falhou com erro de variável vazia	Contato não tinha o campo mapeado preenchido no momento do disparo	Corrija os dados do contato e crie nova campanha para os contatos que falharam
Mensagem final ultrapassou o limite da Meta	Valor do campo substituído é muito longo (acima de 1.024 caracteres)	Evite mapear variáveis para campos de texto livre longos. Prefira campos curtos como nome, cargo e empresa
Erro "use nome completo do contato" ao inserir variável	Uso de `var_contact_first_name` ou `var_contact_last_name` em template HSM — bloqueadas pela Meta	Substitua por `var_contact_name` (nome completo). A plataforma exibirá essa sugestão automaticamente

Perguntas frequentes

O que acontece se o contato não tiver o campo mapeado preenchido?

A mensagem não será enviada para esse contato. O enrollment fica marcado como falha com indicação de campo vazio. O sistema nunca envia um template com variável em branco. Para evitar isso, filtre a audiência para incluir apenas contatos com o campo preenchido antes de lançar.

Posso usar texto fixo como valor de uma variável?

Não. O mapeamento aceita apenas campos de contato. Se você precisa de um valor fixo em uma posição do template, inclua-o diretamente no texto do template ao submetê-lo para aprovação na Meta, não como variável.

Posso usar o mesmo template em várias etapas da mesma campanha?

Sim. Você pode selecionar o mesmo template aprovado em múltiplas etapas com mapeamentos iguais ou diferentes. Isso é útil em sequências de follow-up onde a estrutura da mensagem é similar mas o contexto muda.

Posso alterar o mapeamento de variáveis depois que a campanha foi lançada?

Não. Após a ativação, o conteúdo das etapas, incluindo o mapeamento de variáveis, é imutável. Se precisar corrigir, pause e arquive a campanha atual e crie uma nova com o mapeamento corrigido.

Se o nome do contato for atualizado depois que a campanha foi lançada, qual valor será enviado?

O valor no momento do disparo da etapa. Ou seja, o valor mais recente do campo. O sistema busca os dados atuais do contato cada vez que uma etapa é executada.

O sistema bloqueia variáveis que violem políticas da Meta?

Sim, parcialmente. Ao criar ou editar um template HSM, a plataforma oculta automaticamente var_contact_first_name e var_contact_last_name do seletor. Se você tentar usá-las manualmente, o sistema exibe um erro sugerindo var_contact_name como substituto. Em campanhas sem HSM, essas variáveis continuam disponíveis.

O preview mostra exatamente o que o contato vai receber?

O preview exibe a mensagem renderizada visualmente com as variáveis substituídas e formatação do WhatsApp aplicada. Ele não exibe o payload técnico enviado à API. Para auditoria técnica, consulte o histórico de execuções após o envio.