1. [Ajuda](https://nuvia.ai/docs) 2. [Campanhas](https://nuvia.ai/docs/colecoes/19377976-campanhas) 3. [Campanhas de Whatsapp](https://nuvia.ai/docs/colecoes/19433179-campanhas-de-whatsapp) # Como usar variáveis em templates WhatsApp na Nuvia Mapeie os campos do contato para as variáveis de um template aprovado e personalize cada mensagem da campanha em escala, com preview em tempo real. Disponível em Todos os planos Quem pode fazer Qualquer usuário com acesso ao módulo Campanhas Atualizado em 9 de setembro de 2026 [Campanhas de Whatsapp](https://nuvia.ai/docs/colecoes/19433179-campanhas-de-whatsapp) 1. [Como criar e lançar uma campanha de WhatsApp na Nuvia](https://nuvia.ai/docs/artigos/14501312-como-criar-e-lancar-uma-campanha-de-whatsapp-na-nuvia) 2. [Como funciona o texto padrão de variáveis em templates](https://nuvia.ai/docs/artigos/16891724-como-funciona-o-texto-padrao-de-variaveis-em-templates) 3. [Como usar variáveis em templates WhatsApp na Nuvia](https://nuvia.ai/docs/artigos/15353096-como-usar-variaveis-em-templates-whatsapp-na-nuvia) 4. [Como verificar sua empresa no Meta](https://nuvia.ai/docs/artigos/16548621-como-verificar-sua-empresa-no-meta) 5. [Boas práticas para templates de marketing Meta](https://nuvia.ai/docs/artigos/16736964-boas-praticas-para-templates-de-marketing-meta) Nesta página 1. O que você precisa antes de começar 2. Configurar variáveis em uma etapa da campanha 3. Verificar o mapeamento pelo preview 4. Campos disponíveis para mapeamento 5. Componentes do template suportados 6. O que acontece no momento do envio 7. Texto padrão: enviar mesmo quando o contato não tem o dado 8. Limites e regras **Nesta página8 seções** 1. O que você precisa antes de começar 2. Configurar variáveis em uma etapa da campanha 3. Verificar o mapeamento pelo preview 4. Campos disponíveis para mapeamento 5. Componentes do template suportados 6. O que acontece no momento do envio 7. Texto padrão: enviar mesmo quando o contato não tem o dado 8. Limites e regras Variáveis de template permitem que uma campanha envie a mesma estrutura de mensagem para centenas de contatos, com nome, empresa ou cargo trocados para cada destinatário. Você liga cada espaço dinâmico (#{{1}}, #{{2}}, #{{3}}) do template a um campo do contato uma única vez, dentro da etapa da campanha, e cada pessoa recebe uma mensagem que parece escrita só para ela. ## O que você precisa antes de começar - Ao menos uma inbox de **[WhatsApp conectada](https://nuvia.ai/docs/artigos/14489425-como-conectar-o-whatsapp-na-nuvia)** na plataforma - Ao menos um **template aprovado pela Meta** associado à inbox que vai usar, com variáveis de texto (#{{1}}, #{{2}}, etc.). **A criação de templates é detalhada em:[Como criar templates de WhatsApp com variáveis](https://nuvia.ai/docs/artigos/14579891-como-criar-templates-de-whatsapp-com-variaveis)** - Os contatos da audiência com os campos que serão mapeados preenchidos (se vai ligar #{{1}} ao nome, os contatos precisam ter o campo **Nome** preenchido). Quando o dado pode faltar, use o **texto padrão** descrito mais abaixo - Acesso ao módulo **Campanhas** na navegação lateral ## Configurar variáveis em uma etapa da campanha O mapeamento acontece no **Passo 3: Sequência de mensagens** da criação de campanha. Cada etapa da sequência tem o seu próprio template e o seu próprio mapeamento, independente das demais. 1. Na navegação lateral, clique em **Campanhas** 2. Clique em **Nova campanha**, ou abra uma campanha existente em status **Rascunho** 3. Preencha o nome, selecione o canal **WhatsApp** e configure a audiência nos passos anteriores 4. No **Passo 3**, clique em **Adicionar etapa** 5. No campo **Conexão**, selecione a inbox (o remetente) pelo dropdown 6. Em **Tipo de envio**, selecione **Template** 7. Clique em **Selecionar template**. O dropdown mostra apenas os templates aprovados da inbox escolhida 8. Escolha o template. A plataforma exibe as variáveis identificadas (ex: #{{1}}, #{{2}}) 9. Para cada variável, escolha no dropdown o campo do contato correspondente (caso os campos das variáveis já tenham sido mapeados no momento da criação do template, não é necessário atribuir os campos): - **Nome**, **E-mail**, **Telefone**, **País** (campos fixos) - Campos customizados criados pelo admin da empresa 10. Se quiser, preencha o **Texto padrão das variáveis**: o texto que entra na mensagem quando o contato não tem aquele dado 11. Acompanhe o **preview** lateral, que atualiza em tempo real com os dados de um contato real da audiência Importante Como criar um template é detalhado no artigo: **[Como criar templates de WhatsApp com variáveis](https://nuvia.ai/docs/artigos/14579891-como-criar-templates-de-whatsapp-com-variaveis)** [GIF: Selecionando um template na campanha] ## Verificar o mapeamento pelo preview O preview lateral usa dados reais de contatos da audiência, não exemplos fictícios. Assim você confere como a mensagem vai chegar para cada prospect antes de lançar. 1. Na lista de etapas, clique na etapa que quer conferir. O preview lateral atualiza sozinho 2. Use as setas **Anterior** e **Próximo** no preview para passar por diferentes contatos da audiência 3. Confira se todas as variáveis aparecem com o valor certo para cada contato 4. Se alguma variável aparecer vazia, a plataforma mostra um aviso de mapeamento incompleto. Corrija antes de lançar O preview já aplica a formatação do WhatsApp: negrito (*texto*), itálico (_texto_) e quebras de linha aparecem como o destinatário vai ver no aplicativo. O valor de cada campo entra no preview exatamente como está cadastrado, inclusive quando tem cifrão ou pontuação (ex: R$ 1.200,00). O texto que você vê no preview é o mesmo texto que sai para o lead. ## Campos disponíveis para mapeamento ### Campos fixos do contato Disponíveis para todos os contatos da plataforma: CampoExemplo de uso no template **Nome** “Olá, #{{1}}! Tudo bem?” vira “Olá, João! Tudo bem?” **E-mail** “Enviei um material para #{{1}}” **Telefone** Raramente usado, já que o envio vai para o número do contato **País** “Vi que você está em #{{1}}…” A plataforma também oferece campos derivados do nome completo, como primeiro nome e sobrenome. ### Campos customizados Campos criados pelo admin da empresa, que aparecem no dropdown de mapeamento. Tanto campos com contexto **Contato** quanto campos com contexto **Misto** aparecem no editor de mensagens da campanha: Exemplo de campoExemplo 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 falar com alguém de #{{1}}!” Importante Campos customizados precisam ser criados pelo admin em **Plataforma** antes de aparecerem no mapeamento. ## Componentes do template suportados Nem todo componente de um template aceita variáveis. O que vale: StatusComponenteSuporte a variáveis ✅ **Header (texto)** Aceita 1 variável (#{{1}}) ✅ **Body** Componente principal, aceita várias variáveis (#{{1}}, #{{2}}, etc.) ❌ **Footer** Não aceita variáveis, é só texto fixo (regra da Meta) ❌ **Botões com texto fixo** Não usam variáveis ⚠️ **Botões de URL dinâmica** Suporte limitado. Confirme com o suporte se a sua inbox e o seu plano cobrem esse caso ## O que acontece no momento do envio As variáveis são resolvidas no momento do disparo de cada etapa, e não no lançamento da campanha. Na prática: - A plataforma busca os dados atuais do contato quando chega a hora de enviar aquela etapa - Se o campo do contato mudar entre uma etapa e outra, a próxima etapa usa o valor atualizado - O valor do campo é inserido no texto exatamente como está cadastrado, sem nenhum tratamento extra de caracteres - Se um contato não tiver o campo mapeado preenchido **e a variável não tiver texto padrão**, a mensagem não é enviada para ele e o enrollment é encerrado como falha - Se a variável **tiver texto padrão**, a mensagem sai normalmente, com esse texto no lugar da variável Importante Quando o envio falha por variável vazia, a falha vem com uma mensagem clara, dizendo qual campo preencher pelo rótulo amigável (ex: “Não foi possível enviar o template: Nome da empresa está vazio neste lead. Preencha o campo e tente novamente.”). Se houver mais de um campo vazio, todos são listados. ## Texto padrão: enviar mesmo quando o contato não tem o dado Dado faltando é rotina: lead novo não tem cidade, contato que chegou por formulário não tem empresa nos primeiros segundos. Antes, uma única variável vazia derrubava a mensagem inteira daquele contato. Com o **texto padrão**, você define o que entra no lugar da variável, e a mensagem sai. ### Onde preencher O bloco **Texto padrão das variáveis** aparece dentro da etapa, tanto no **Passo 3** da criação (em **Adicionar etapa**) quanto ao criar ou editar uma etapa na tela da campanha. Ele vale para os dois tipos de envio: - **Template**: o bloco aparece depois que você seleciona o template, com um campo por variável do template - **Texto**: o bloco aparece abaixo do campo de mensagem, com um campo por variável que você digitou Cada campo é identificado pelo nome da variável (ex: #{{var_contact_city}}), e o subtítulo do bloco resume a regra: “Opcional. Se o contato não tiver o dado, a mensagem é enviada com este texto no lugar da variável, em vez de não ser enviada.” 1. Configure a etapa normalmente (inbox, tipo de envio, template ou texto) 2. No bloco **Texto padrão das variáveis**, preencha o campo da variável que quer proteger (ex: para a cidade, escreva **sua região**) 3. Deixe em branco as variáveis que **não** quer proteger. Campo vazio significa “sem texto padrão”, ou seja, o comportamento antigo 4. Salve a etapa Dica Proteja as variáveis de dado opcional (cidade, setor, cargo) e deixe sem texto padrão as que são o coração da mensagem. Se o nome da empresa é a personalização inteira da abordagem, é melhor não enviar do que enviar “sua empresa”. ### O que o texto padrão faz e o que não faz SituaçãoO que acontece Contato sem o campo preenchido, variável **com** texto padrão A mensagem é enviada com o texto padrão no lugar da variável Contato com o campo existente, mas **vazio** Igual ao caso acima: o texto padrão também entra Contato sem o campo preenchido, variável **sem** texto padrão Continua como antes: o envio falha e a falha nomeia o campo Contato com o campo preenchido O valor real do contato sempre vence. O texto padrão só entra na ausência do dado Variável de **coluna de lista** (var_col_) O texto padrão **não** se aplica. Coluna de lista vazia continua derrubando o envio Template enviado manualmente de dentro de uma **conversa** O texto padrão **não** se aplica: ele é configuração da etapa da campanha ### Regras de preenchimento O texto padrão é validado quando você salva a etapa. Três coisas fazem a plataforma recusar: RegraMensagem de erro Sem quebra de linha, tabulação ou mais de quatro espaços seguidos “Texto padrão de X não pode ter quebra de linha, tabulação ou mais de quatro espaços seguidos.” Um texto padrão sozinho não pode estourar o limite de caracteres da mensagem “Texto padrão de X excede o limite da mensagem: cabem N caracteres.” A soma de todos os textos padrão da etapa não pode estourar o limite “Os textos padrão somados excedem o limite da mensagem: cabem N caracteres para todos juntos.” O cálculo já desconta o espaço do próprio #{{…}}, que desaparece quando o texto padrão entra. O campo também limita a digitação pela folga disponível, como orientação: a recusa definitiva é da plataforma no momento de salvar. Importante Em etapas de **template**, a plataforma valida apenas as regras de caractere ao salvar, e não o comprimento: o corpo do template é o aprovado na Meta e não passa por essa conta. O limite da Meta continua valendo no envio, então mantenha o texto padrão curto. Bom saber Se você editar a mensagem e remover uma variável, o texto padrão que ficou órfão é descartado no próximo salvamento. Não é erro e não trava a edição, mas você precisa preenchê-lo de novo se reinserir a variável. ## Limites e regras RegraValor **Número de variáveis por template** Definido na criação e aprovação do template. A Nuvia não adiciona limite próprio ao mapeamento **Limite de caracteres** O corpo da mensagem, já com as variáveis preenchidas, não pode passar de 1.024 caracteres (limite da Meta) **Tipos de variável** Apenas variáveis de texto (#{{n}}). Variáveis de mídia (imagem, vídeo, documento) precisam de configuração separada **Origem dos dados** Apenas campos do contato (fixos ou customizados). Não é possível inserir texto livre como valor **Texto padrão por variável** Opcional, definido na etapa da campanha. Vale para etapas de **template** e de **texto**. Não vale para variáveis de coluna de lista (var_col_) nem para template enviado manualmente pela conversa **Caracteres proibidos no texto padrão** Quebra de linha, tabulação e mais de quatro espaços seguidos **Comprimento do texto padrão** Cada texto padrão, e a soma de todos os da etapa, tem que caber no limite de caracteres da mensagem. Em etapas de template o comprimento não é validado ao salvar, só as regras de caractere **Caracteres especiais no valor** O valor do campo entra na mensagem exatamente como está cadastrado, incluindo cifrão e pontuação (ex: R$ 1.200,00). Não é preciso escapar nada, e o preview mostra o mesmo texto que sai para o lead **Templates disponíveis** Apenas templates com status **Aprovado** pela Meta **Filtro por inbox** O dropdown mostra só os templates da inbox selecionada na etapa **Depois da ativação** O mapeamento e o texto padrão fazem parte do conteúdo da etapa e não podem ser alterados após a campanha entrar em status **AtivaRecomendação** 2 a 3 variáveis por template. A Meta também rejeita templates com variáveis demais para o tamanho da mensagem **Variáveis nas bordas** O corpo não pode começar nem terminar com variável, mesmo seguida ou precedida de pontuação (ex: #{{1}}?, ? #{{1}}). A plataforma bloqueia o salvamento com a mensagem “O corpo da mensagem não pode começar ou terminar com variáveis” ## Perguntas frequentes **O que acontece se o contato não tiver o campo mapeado preenchido?** Depende de você ter definido um texto padrão para aquela variável. Com texto padrão, a mensagem é enviada normalmente, com o texto no lugar da variável. Sem texto padrão, a mensagem não é enviada para esse contato e a falha nomeia o campo vazio pelo rótulo amigável (ex: “Não foi possível enviar o template: Nome da empresa está vazio neste lead. Preencha o campo e tente novamente.”). A plataforma nunca envia um template com variável em branco. Outra forma de evitar a falha é filtrar a audiência para incluir só contatos com o campo preenchido antes de lançar. **Como faço a mensagem sair mesmo quando o contato não tem o dado?** Preencha o bloco **Texto padrão das variáveis** na etapa. Para cada variável você escreve o texto que entra quando o contato não tiver aquele campo (ex: “sua região” para a cidade). Campo em branco significa “sem texto padrão” e mantém o comportamento antigo: variável vazia derruba o envio daquele contato. **O texto padrão vale também quando o campo existe mas está vazio?** Sim. Tanto o campo que não existe no contato quanto o campo cadastrado em branco acionam o texto padrão. **Se o contato tiver o dado, o texto padrão atrapalha?** Não. O valor real do contato sempre vence. O texto padrão só é usado na ausência do dado. **O texto padrão vale para variáveis de coluna de lista?** Não. Variáveis de coluna de lista (var_col_) são resolvidas por outro caminho e continuam derrubando o envio quando a coluna está vazia naquele contato. Garanta a coluna preenchida na Lista antes de lançar. **Posso definir texto padrão para um template que eu envio manualmente pela conversa?** Não. O texto padrão é configuração da etapa da campanha. No envio manual de template pela conversa, a variável vazia continua bloqueando o envio, com a mensagem clara para o atendente. **Posso usar texto fixo como valor de uma variável?** Não. O mapeamento aceita apenas campos de contato, fixos ou customizados. Se precisa de um valor fixo numa posição do template, inclua o texto direto no template ao submetê-lo para aprovação na Meta, não como variável. O texto padrão é diferente: ele não substitui o mapeamento, só entra quando o campo mapeado está vazio. **Posso usar cifrão (R$) no valor de uma variável?** Sim. O valor do campo é inserido na mensagem exatamente como está cadastrado no contato ou na coluna da lista: R$ 1.200,00 chega como R$ 1.200,00. Isso vale tanto para o texto que sai para o lead quanto para o preview, que mostra o mesmo resultado. O mesmo se aplica a qualquer outra pontuação no valor do campo. **Posso usar o mesmo template em várias etapas da campanha?** Sim. Você pode selecionar o mesmo template aprovado em várias etapas, com mapeamentos iguais ou diferentes. Isso ajuda em sequências de follow-up, em que a estrutura da mensagem é parecida, mas o contexto muda. **Posso alterar o mapeamento depois que a campanha foi lançada?** Não. Depois da ativação, o conteúdo das etapas, incluindo o mapeamento e o texto padrão, fica imutável. Para corrigir, pause e arquive a campanha atual e crie uma nova com o mapeamento certo. **Se o nome do contato for atualizado depois do lançamento, qual valor é enviado?** O valor no momento do disparo da etapa, ou seja, o mais recente. A plataforma busca os dados atuais do contato a cada execução de etapa e não congela os dados no lançamento. **Se uma etapa falhar por variável vazia, o contato continua nas próximas etapas?** Não. Quando o disparo de uma etapa falha por variável vazia, o enrollment daquele contato é encerrado e as etapas seguintes não são executadas para ele. Por isso o texto padrão precisa estar definido na etapa antes do disparo. **O que acontece se eu trocar o template depois de mapear as variáveis?** A plataforma limpa todos os mapeamentos anteriores. Cada template pode ter variáveis com significados diferentes, então é preciso refazer o mapeamento do zero para o novo template. **Existe limite de disparos por minuto quando uso variáveis?** Não. As variáveis não mudam a velocidade de envio. Valem os mesmos limites de qualquer campanha de WhatsApp: a capacidade da inbox e os limites da API. **O preview mostra exatamente o que o contato vai receber?** O preview mostra a mensagem renderizada, com as variáveis substituídas e a formatação do WhatsApp aplicada. Ele não mostra o payload técnico (JSON) enviado para a API. Para auditoria técnica, consulte o histórico de execuções depois do envio. **O template pode começar ou terminar com uma variável?** Não. A Meta rejeita templates cujo corpo começa ou termina com variável, e a plataforma valida isso antes do envio, inclusive quando a variável vem com pontuação, como #{{1}}? ou #{{1}}!. Se aparecer o erro “O corpo da mensagem não pode começar ou terminar com variáveis”, mova a variável para o meio do texto. [AnteriorComo funciona o texto padrão de variáveis em templates](https://nuvia.ai/docs/artigos/16891724-como-funciona-o-texto-padrao-de-variaveis-em-templates) [PróximoComo verificar sua empresa no Meta](https://nuvia.ai/docs/artigos/16548621-como-verificar-sua-empresa-no-meta) Este artigo ajudou? ## Artigos relacionados - [Como criar e lançar a sua primeira campanha de WhatsApp na Nuvia](https://nuvia.ai/docs/artigos/14489458-como-criar-e-lancar-a-sua-primeira-campanha-de-whatsapp-na-nuvia) - [Entendendo as regras do WhatsApp: janela de 24h, 72h e templates](https://nuvia.ai/docs/artigos/14575042-entendendo-as-regras-do-whatsapp-janela-de-24h-72h-e-templates) - [Como criar e lançar a sua primeira campanha de LinkedIn na Nuvia](https://nuvia.ai/docs/artigos/15181600-como-criar-e-lancar-a-sua-primeira-campanha-de-linkedin-na-nuvia) - [Como disparar templates WhatsApp na Nuvia direto de um workflow do HubSpot](https://nuvia.ai/docs/artigos/15879535-como-disparar-templates-whatsapp-na-nuvia-direto-de-um-workflow-do-hubspot) [Campanhas de Whatsapp](https://nuvia.ai/docs/colecoes/19433179-campanhas-de-whatsapp) 1. [Como criar e lançar uma campanha de WhatsApp na Nuvia](https://nuvia.ai/docs/artigos/14501312-como-criar-e-lancar-uma-campanha-de-whatsapp-na-nuvia) 2. [Como funciona o texto padrão de variáveis em templates](https://nuvia.ai/docs/artigos/16891724-como-funciona-o-texto-padrao-de-variaveis-em-templates) 3. [Como usar variáveis em templates WhatsApp na Nuvia](https://nuvia.ai/docs/artigos/15353096-como-usar-variaveis-em-templates-whatsapp-na-nuvia) 4. [Como verificar sua empresa no Meta](https://nuvia.ai/docs/artigos/16548621-como-verificar-sua-empresa-no-meta) 5. [Boas práticas para templates de marketing Meta](https://nuvia.ai/docs/artigos/16736964-boas-praticas-para-templates-de-marketing-meta) ## Ainda precisa de ajuda? Clientes falam com o suporte pelo chat dentro da plataforma. Ainda não é cliente? Fale com o nosso time. [Falar com o suporte na plataforma](https://app.nuvia.ai) [Ainda não sou cliente](https://nuvia.ai/contact) --- Source: https://nuvia.ai/docs/artigos/15353096-como-usar-variaveis-em-templates-whatsapp-na-nuvia