## 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, o seletor mostra o que a variável
   selecionada vai produzir para aquele contato — o nome real, o valor real da cobrança, a data real
   do agendamento. Digitando `{{`, o valor aparece no painel de prévia, no campo **Valor**; pelo
   botão `{x}`, ele aparece como uma etiqueta na própria linha do token. O que aparece ali é
   exatamente o que o cliente vai receber.
6. Envie um teste antes de disparar para a base inteira.

## Configurações & opções

### O seletor de variáveis

Há duas formas de chegar à mesma lista:

- **Digitando `{{`** dentro do editor. O seletor abre ancorado ao ponto onde você está escrevendo,
  acima ou abaixo daquela linha — o lado da tela com mais espaço vence — e já com o campo de busca em
  foco: continue digitando e a lista filtra.
- **Pelo botão `{x} Inserir`**, no cabeçalho dos campos que o oferecem (modelos de WhatsApp, passos de
  follow-up, lembretes da agenda, campos do construtor de fluxo).

Nos dois casos a busca casa tanto com o **nome do token** quanto com a **descrição** — procurar por
"vencimento" encontra a variável mesmo que você não saiba o nome dela.

**A lista nunca é reordenada.** Grupos e tokens vêm na ordem do catálogo do servidor, que já coloca o
mais usado primeiro (`name`, `first_name`, `email`… antes dos campos de endereço). Os campos
personalizados que você criou entram no grupo do próprio modelo a que pertencem.

**O painel de prévia** mostra dois campos do item selecionado:

| Campo | O que traz |
|---|---|
| **Descrição** | O que a variável significa, no idioma do painel |
| **Valor** | O que ela vai produzir **nesta conversa**, calculado no servidor pelo mesmo mecanismo que monta a mensagem no envio |

Quando o token não tem valor para aquele contato, o painel diz **"Sem valor para esta conversa"** em
texto apagado, em vez de fingir um valor que não existe. É a resposta honesta — e é exatamente o que
você precisa ver antes de enviar.

Em telas largas o painel fica à direita da lista; em telas estreitas ele desce para baixo dela; e
quando não cabe de nenhum dos dois jeitos, o seletor mostra só a lista, que continua funcionando
igual.

**Teclado:** ↑ ↓ (ou Tab / Shift+Tab, ou Ctrl+P / Ctrl+N) percorrem a lista, que dá a volta do último
item para o primeiro; **Enter** insere; **Esc** fecha e devolve o foco ao texto; **Backspace com a
busca vazia** apaga o `{{` que abriu o seletor. Passar o mouse sobre uma linha já a seleciona, clicar
insere e clicar fora fecha.

**Onde o `{{` não abre.** O gatilho só é reconhecido no início da linha ou depois de um espaço, e o
seletor **não abre em nota privada** — escolher a variável na lista é um recurso do modo Resposta.
Depois de fechado com `Esc`, ele só reabre quando você digita `{{` de novo.

### 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.

### Sinais do Cérebro da Conta

As variáveis `{{ brain.* }}` descrevem **a conversa em que a mensagem é escrita**:

- `{{ brain.risk_score }}` e `{{ brain.risk_band }}` mostram o risco **daquela conversa** ou, se ela
  ainda não tiver uma leitura, o do **contato dela**. Sem nenhuma das duas, ficam em branco — nunca
  mostram o risco de outra conversa.
- `{{ brain.insight_type }}`, `{{ brain.insight_severity }}` e `{{ brain.department }}` mostram o
  insight daquela conversa ou do contato dela e, se não houver, o **insight mais recente da conta
  como um todo** (por exemplo, um indicador de atendimento). Insights de outras conversas e insights
  marcados como **sensíveis** nunca aparecem em variáveis.

O valor que o seletor mostra é o mesmo que a mensagem recebe ao ser enviada, para qualquer pessoa que
possa escrever naquela conversa. Em fluxos que rodam sem conversa nem contato, o risco é a leitura
mais recente da conta e o insight é o mais recente da conta como um todo.

### Data e hora no fuso da conta

`{{ now.date }}`, `{{ now.time }}`, `{{ now.datetime }}` e os demais valores de `now` usam o **fuso definido nas configurações da conta**, inclusive no Flow Builder. Os tokens `*_formatted` também projetam os horários nesse fuso. `{{ now.timezone }}` e `{{ account.timezone }}` mostram qual fuso está valendo. Sem um fuso configurado ou herdado do onboarding ou da configuração legada, a conta usa **UTC**, mesmo se o servidor tiver outro fuso.

Os filtros Liquid `| date`, `| datetime` e `| time_of_day` também usam o **fuso configurado na conta**, assim como `{{ now.* }}` e os tokens `*_formatted`. Por exemplo, `{{ contact.created_at | datetime }}` mostra o instante no relógio da conta.

Com formato explícito, como `| date: '%H:%M'`, um instante com offset ou `Z` também usa o fuso da conta. Uma data pura conserva o dia escrito; uma string com data e hora sem offset conserva os dígitos escritos, sem deslocamento de fuso.

As condições de data do Flow Builder interpretam datas sem indicação de fuso, como `2026-10-06 00:00`, no fuso da conta. Uma data ISO com offset explícito mantém seu instante. Em fluxos já publicados, revise comparações que antes dependiam de UTC. A condição de estar dentro de N dias continua comparando uma duração de N × 24 horas.

### 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.
- **`Esc` fecha, Backspace apaga.** `Esc` fecha o seletor mas mantém o `{{` no texto — útil quando
  você queria mesmo escrever chaves. Para tirar o gatilho junto, use **Backspace com o campo de busca
  vazio**.
- **O que você digita depois do `{{` vai para a busca, não para a mensagem.** O campo de busca do
  seletor toma o foco assim que ele abre.
- **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 |
| Digitei `{{` e o seletor não abriu | Você está numa **nota privada**, onde o seletor não abre — ou o `{{` não veio no início da linha nem depois de um espaço | Volte ao modo Resposta para escolher a variável na lista; numa anotação interna, escreva o valor por extenso |
| O painel diz "Sem valor para esta conversa" | O token não tem dado para este contato | Confira o cadastro; ajuste a frase para funcionar sem o valor, ou escolha outra variável |
| O seletor abriu sem o painel de prévia | Não havia espaço na tela para ele | Alargue a janela ou dê mais altura ao editor — a lista funciona igual sem a prévia |

## Veja também

- [Modelos de mensagem por módulo](/hc/ajuda/articles/administration-conta-agentes-equipes-pt-br)
- [Responder, notas privadas e menções a colegas](/hc/ajuda/articles/conversations-responder-notas-mencoes-pt-br)