## Visão geral

Variáveis dinâmicas deixam você escrever **uma** mensagem que chega personalizada para cada pessoa.
Em vez de "Olá!", você escreve `Olá {{ contact.first_name }}!` e cada contato recebe o próprio nome.

A variável é sempre escrita entre chaves duplas e resolvida **no servidor**, no momento do envio —
nunca no navegador. Se o dado não existir, a variável vira texto vazio, e o restante da mensagem
segue normalmente.

Todas as variáveis usam o mesmo vocabulário em **todas** as superfícies: o que funciona no compositor
de resposta funciona igual no e-mail, na campanha, no follow-up, no fluxo e no contrato.

## Pré-requisitos

- Nenhum. As variáveis básicas (contato, conta, caixa de entrada, agente) funcionam desde o primeiro dia.
- As variáveis de um módulo (cobrança, agendamento, contrato, pedido…) só trazem valor quando aquele
  módulo está em uso na conta. Sem dado, elas resolvem vazio — nunca quebram a mensagem.

## Passo a passo

1. Abra qualquer campo de texto que aceite variáveis (compositor, macro, resposta rápida, campanha,
   follow-up, contrato, lembrete da agenda…).
2. Digite `{{` — a lista de variáveis aparece automaticamente.
3. Ou clique no botão **`{x}` Inserir variável**, quando disponível no cabeçalho do campo.
4. Busque pelo nome (por exemplo "valor" ou "vencimento") e clique para inserir.
5. **Confira o valor antes de enviar.** Dentro de uma conversa, cada variável da lista mostra ao
   lado o que ela vai produzir para aquele contato — o nome real, o valor real da cobrança, a data
   real do agendamento. O que aparece ali é exatamente o que o cliente vai receber.
6. Envie um teste antes de disparar para a base inteira.

## Configurações e opções

### Os grupos disponíveis

| Grupo | Para que serve | Exemplo |
|---|---|---|
| Contato | Quem está do outro lado | `{{ contact.first_name }}` |
| Conversa | A conversa atual | `{{ conversation.display_id }}` |
| Conta / Marca | Sua empresa | `{{ account.name }}` · `{{ brand.name }}` |
| Agente | Quem atende | `{{ agent.available_name }}` |
| Data e hora | O relógio, no fuso da conta | `{{ now.date }}` · `{{ now.weekday }}` |
| Negócio (CRM) | O negócio ligado ao contato | `{{ crm.title }}` · `{{ crm.value_formatted }}` |
| Empresa | A empresa do contato | `{{ organization.legal_name }}` |
| Cobrança | A cobrança mais recente | `{{ payment.pay_url }}` · `{{ payment.due_date_formatted }}` |
| Assinatura | O plano recorrente | `{{ subscription.next_due_date_formatted }}` |
| Pedido | O pedido mais recente | `{{ order.amount_formatted }}` |
| Agendamento | O agendamento do contato | `{{ booking.date_formatted }}` · `{{ booking.manage_url }}` |
| Contrato | O contrato em aberto | `{{ contract.sign_url }}` |
| Tarefa | A tarefa ligada ao contato | `{{ task.due_at_formatted }}` |
| Carrinho e checkout | Recuperação de venda | `{{ commerce.pay_url }}` |
| Produto | O produto citado | `{{ product.price_formatted }}` |
| Grupo | Grupo de WhatsApp / turma | `{{ group.invite_url }}` |
| Time · SLA · Disponibilidade | Operação | `{{ team.name }}` · `{{ wfm.online }}` |
| Satisfação · Engajamento | Relacionamento | `{{ csat.rating }}` · `{{ engagement.tier }}` |
| Vendedor · Meta · Comissão · Afiliado | Vendas | `{{ seller.name }}` · `{{ affiliate.referral_code }}` |
| Anúncio · Lead | Origem paga | `{{ lead.headline }}` |
| Artigo | Central de Ajuda | `{{ article.url }}` |
| Cérebro da Conta | Sinais de IA | `{{ brain.risk_band }}` |

O seletor mostra apenas os grupos que **funcionam naquela tela**. Uma campanha, por exemplo, não tem
conversa, então variáveis de conversa não são oferecidas ali.

### Valores formatados

Todo valor de dinheiro e de data existe em duas formas:

- **Crua** — o valor como está guardado: `{{ crm.value_amount }}` → `1500.0`
- **Formatada** — pronta para o cliente ler: `{{ crm.value_formatted }}` → `R$ 1.500,00`

O mesmo vale para datas: `{{ payment.due_date }}` → `2026-08-08` e
`{{ payment.due_date_formatted }}` → `08/08/2026`, sempre na moeda, no idioma e no **fuso da sua conta**.

Se um valor não tiver a versão formatada, você pode formatar na hora com um filtro:

```
{{ payment.amount | money: 'BRL' }}   →  R$ 1.500,00
{{ booking.starts_at | datetime }}    →  08/08/2026 14:30
```

### Campos personalizados

Os campos personalizados que você criou também viram variáveis, no formato
`{{ contact.custom_attribute.chave }}`. Isso vale para os campos de contato, conversa, empresa,
negócio, produto, tarefa, grupo, cobrança, agendamento, follow-up e contrato.

## Casos de uso

- **Cobrança vencida:** `Oi {{ contact.first_name }}, sua fatura de {{ payment.amount_formatted }} venceu em {{ payment.due_date_formatted }}. Pague aqui: {{ payment.pay_url }}`
- **Lembrete de agendamento:** `Seu horário é {{ booking.date_formatted }} às {{ booking.time_formatted }} com {{ booking.host }}. Precisa remarcar? {{ booking.manage_url }}`
- **Contrato:** `{{ contact.first_name }}, seu contrato "{{ contract.title }}" está pronto: {{ contract.sign_url }}`
- **Convite de grupo:** `Bem-vindo! Entre na {{ group.name }}: {{ group.invite_url }}`

## Dicas, limites e boas práticas

- **Sempre envie um teste.** É a forma mais rápida de ver se a variável trouxe o valor esperado.
- **Dado ausente vira vazio.** Escreva a frase de modo que ela continue fazendo sentido sem o valor —
  evite "Seu pedido de  chegou".
- **Em campanhas, cuidado redobrado.** Se uma variável usada no modelo aprovado não resolver para um
  destinatário, aquele destinatário é **pulado**. Prefira variáveis que você tem certeza de que existem.
- **Documento fiscal:** em mensagens, o CPF/CNPJ só aparece **mascarado** (`{{ contact.masked_tax_id }}`).
  O documento completo é exclusivo de contratos, onde a própria pessoa assina.
- **Não invente variáveis.** Se não está no seletor, não existe — e vai sair vazia.
- **Onde o valor não aparece.** Fora de uma conversa (macro, resposta rápida, campanha, modelo de
  contrato) não há contato definido ainda, então a lista mostra só o nome da variável. É o
  comportamento correto: ali a variável ainda não tem um dono.
- **Se o seu papel esconde um dado, o valor aparece escondido também.** Um agente que vê
  `a***@example.com` no cadastro vê `a***@example.com` na lista de variáveis — a mensagem enviada é
  que carrega o valor real.

## Solução de problemas

| Sintoma | Causa provável | O que fazer |
|---|---|---|
| A mensagem chegou com `{{ ... }}` literal | A variável foi digitada num campo que não resolve variáveis | Use o seletor: ele só aparece onde as variáveis funcionam |
| A variável saiu vazia | O dado não existe para aquele contato | Confira o cadastro; ajuste a frase para funcionar sem o valor |
| O valor saiu como `1500.0` | Você usou a versão crua | Troque por `{{ ...value_formatted }}` |
| A data veio com um dia de diferença | Fuso da conta diferente do esperado | Ajuste o fuso em Configurações da conta |
| A campanha pulou destinatários | Variável sem valor no modelo aprovado | Reveja o modelo e use variáveis mais seguras |
| O aviso "variáveis não definidas" aparece numa variável que funciona | A variável realmente não tem valor **para este contato** | Olhe o valor ao lado dela na lista: se estiver em branco, o dado não existe no cadastro |

## Veja também

- [Modelos de mensagem por módulo](/hc/ajuda/articles/administration-conta-agentes-equipes-pt-br)