---
title: Variáveis
description: Guarde, combine e transforme valores dentro do seu fluxo com os nós de variável.
---

# Variáveis  ·  `set_variable` / `assigner` / `variable_assigner`

<NoCard kind="assigner / set_variable / variable_assigner" categoria="Dados" />

<Secao icon="info">Para que serve</Secao>

Pensa num bloco de notas que fica do seu lado durante o atendimento. Você anota o nome do cliente, o número do pedido, a resposta que ele deu — e a qualquer momento pode consultar, mudar ou apagar esse conteúdo. Os nós de variável fazem exatamente isso: guardam informações para você usar mais à frente no fluxo.

<Secao icon="clock">Quando usar</Secao>

- Salvar a escolha que o cliente fez num menu de botões
- Construir uma mensagem personalizada juntando nome + produto + data
- Acumular itens numa lista ao longo de uma iteração
- Limpar o valor de uma variável antes de começar um novo ciclo
- Mesclar dados de fontes diferentes numa saída tipada e organizada

---

## Os três nós de variável

O Flow Builder tem três nós com funções parecidas mas objetivos diferentes. Veja qual usar em cada situação:

| Nó | Kind | Para que usar |
|----|------|---------------|
| **Atribuir Variável** | `assigner` | Criar ou alterar variáveis uma a uma, com controle de operação |
| **Variável (legado)** | `set_variable` | Versão antiga — ainda funciona, mas prefira o `assigner` |
| **Mesclar Variáveis** | `variable_assigner` | Combinar N entradas em uma saída tipada (texto, número, objeto…) |

---

## Nome do nó e referência nas variáveis

Além das variáveis declaradas no Gerenciador, cada nó do fluxo expõe suas próprias saídas — e você as referencia pelo **nome do nó**, não por um código interno.

Ao criar um nó novo, ele já nasce com um id legível derivado do tipo: um nó Agente de IA vira `agente`, um segundo Agente de IA na mesma tela vira `agente_2`, e assim por diante. Isso substitui o esquema antigo de ids opacos como `n_agent_1722538_3`.

Você pode trocar esse nome a qualquer momento pelo título editável no topo do painel de configuração (veja [A tela do Flow Builder](/guia/flow-builder/a-tela) para o quadro completo da interface). Ao confirmar, o nome digitado vira o **id** do nó: acentos são removidos, tudo vira minúsculas e espaços viram `_` — "Consulta CPF" vira `consulta_cpf`. Se o resultado colidir com o id de outro nó, ganha um sufixo numérico (`consulta_cpf_2`, `consulta_cpf_3`...).

<Secao icon="circle-check">Exemplo</Secao>

Um nó Agente de IA renomeado para "Consulta CPF" tem sua saída referenciada assim:

```
{{consulta_cpf.resposta}}
```

Em vez do antigo <code v-pre>{{n_agent_1722538_3.resposta}}</code> — muito mais fácil de ler e de manter conforme o fluxo cresce.

<Dica>

Renomear é seguro: todas as referências existentes no fluxo — templates <code v-pre>{{ }}</code>, expressões, condições e os ponteiros de conexão entre nós — são reescritas automaticamente para o novo nome. Nada quebra.

</Dica>

<Cuidado>

Amostras de execuções anteriores à renomeação (usadas para sugerir campos no seletor de variáveis) ficam associadas ao nome antigo até o nó rodar de novo. Enquanto isso, o seletor volta a usar a estrutura de campos já conhecida do nó — a variável continua funcionando, só a sugestão automática fica temporariamente menos rica.

</Cuidado>

---

## Escopos de variável

Toda variável pertence a um escopo, que define quem enxerga ela e por quanto tempo ela vive:

| Escopo | Prefixo | Vive por quanto tempo |
|--------|---------|----------------------|
| **Fluxo** | `flow.` | Durante toda a execução do fluxo; legível em qualquer nó |
| **Local** | `local.` | Apenas dentro do nó/escopo atual |
| **Contato** | `contact.` | Associado ao contato; persiste entre execuções |
| **Workspace** | `workspace.` | Compartilhado por todos os fluxos do workspace |

Você declara essas variáveis no **Gerenciador de Variáveis** (ícone de chaves `{}` na topbar do editor), escolhendo o escopo desejado na hora de criar. Depois de declaradas, elas aparecem no **seletor de variáveis** de cada nó, agrupadas por escopo, junto com as saídas dos nós anteriores, Sistema (`sys.`), Evento (`event.`) e Contato.

Para referenciar uma variável numa expressão, use a notação pontuada com o prefixo do escopo: <code v-pre>{{flow.nome_lead}}</code>, <code v-pre>{{contact.email}}</code>.

<Cuidado>

A referência precisa do **ponto do escopo**. <code v-pre>{{flow.x}}</code> funciona, mas <code v-pre>{{x}}</code> sozinho — sem escopo — não é interpolado e fica literal na mensagem.

</Cuidado>

Quando o mesmo nome de variável existe em mais de um escopo, vale a ordem de precedência **Local > Fluxo > Contato > Workspace**: o escopo mais interno sempre vence.

<Cuidado>

Se você **trocar o escopo** de uma variável já declarada (ex.: de **Fluxo** para **Contato**), os nós que já a referenciavam continuam apontando para o escopo antigo. Revise os nós de **condição** e **atribuição** que usam a variável: declarar em `contact.` e ler em `flow.` nunca casa — a condição simplesmente lê vazio.

</Cuidado>

### Valor padrão

Ao declarar uma variável no **Gerenciador de Variáveis**, o **valor padrão** é aplicado automaticamente no início de cada execução — a variável já nasce preenchida, sem precisar de um nó `assigner` só para inicializá-la.

Duas regras importantes:

- O padrão **só entra quando a variável ainda não tem valor**. Se o disparo do fluxo já trouxe um valor (ex.: dados do evento, do contato ou de uma execução retomada), esse valor vence e o padrão é ignorado.
- O padrão respeita o **tipo** escolhido na declaração. Um padrão `0` numa variável do tipo **Número** vira o número zero (não o texto `"0"`), e `false` numa variável **Booleano** vira falso de verdade — então dá para usar direto numa condição sem conversão.

<Cuidado>

Deixar o campo de valor padrão **em branco** numa variável de tipo Número, Booleano, Objeto ou Array significa "sem padrão" — a variável simplesmente não é criada. Se você quer começar em zero, escreva `0`.

</Cuidado>

### Variáveis do contato persistem de verdade

O escopo **Contato** (`contact.`) é gravado no cadastro do contato. Tudo que o fluxo escrever em `contact.` fica salvo ao fim da execução e é carregado de volta na **próxima** execução — inclusive em outro fluxo, dias depois.

É o lugar certo para memória de longo prazo do lead: estágio da qualificação, preferências, se já recebeu determinada oferta.

<Dica>

Quando o disparo traz um dado atualizado do contato (nome, telefone) e existe uma variável salva com o mesmo nome, o dado do disparo — mais recente — é o que vale naquela execução.

</Dica>

### Variáveis de workspace também persistem de verdade

O escopo **Workspace** (`workspace.`) é compartilhado por **todos os fluxos** do workspace, não só pelo contato atual. Tudo que um fluxo escrever em `workspace.` fica salvo e disponível para qualquer outro fluxo, em qualquer execução futura — é o lugar certo para configuração operacional viva: um contador global, um indicador de campanha ativa, o último ID processado de uma sincronização.

Declare a variável no **Gerenciador de Variáveis** com escopo Workspace, ou deixe que um `assigner`/`variable_assigner` a crie na primeira escrita.

<Dica>

Diferente do escopo Contato, o Workspace não tem "dono" — cuidado com escrita concorrente vinda de execuções paralelas. Prefira nomes específicos (`ultima_sincronizacao_crm`) a nomes genéricos (`status`) para evitar que fluxos diferentes pisem na mesma variável sem querer.

</Dica>

<Cuidado>

Alguns nomes são reservados pelo próprio motor de execução e nunca são gravados no escopo Workspace, mesmo que um `assigner` tente: `workflow_id`, `workflow_run_id`, `timestamp`, `user_id`, `app_id`. A escrita nesses nomes é ignorada silenciosamente (sem erro no fluxo).

</Cuidado>

### Contato cliente: `event.contact.is_client` e `event.contact.legal_provider`

No gatilho **Mensagem Recebida** (`inbound_message`), o evento traz duas variáveis sobre o cadastro do contato no sistema jurídico conectado ao workspace:

| Variável | Tipo | O que contém |
|----------|------|--------------|
| <code v-pre>{{event.contact.is_client}}</code> | Booleano | Verdadeiro quando o contato já está cadastrado como cliente no sistema jurídico conectado ao workspace |
| <code v-pre>{{event.contact.legal_provider}}</code> | Texto | Qual sistema jurídico tem o cadastro: `advbox` ou `meu_estagiario`. Vem vazio quando o contato não é cliente |

O uso típico é uma condição logo após o Start: se `is_client` for verdadeiro, o fluxo entra na trilha de cliente (consulta de processos, agenda); se for falso, entra na trilha de prospecção.

<Dica>

`is_client` **não mudou de nome nem de significado** com a entrada do segundo sistema jurídico. Fluxos publicados que já usam essa variável continuam funcionando exatamente como antes — o que mudou foi apenas de onde o sistema lê a informação internamente. A variável `legal_provider` é nova e opcional: use quando o fluxo precisar se comportar de um jeito diferente para cada sistema.

</Dica>

---

## Nó Atribuir Variável (`assigner`)

<Secao icon="list-checks">Passo a passo</Secao>

<Passos>
  <Passo>Arraste o nó **Atribuir Variável** para o canvas e conecte-o ao bloco anterior.<br/><Captura legenda="Paleta de nós aberta no canvas do Flow Builder, com as categorias disponíveis para localizar e arrastar o nó desejado" src="/img/flowbuilder-paleta-aberta.png" /></Passo>
  <Passo>No painel à direita, clique em **+ Adicionar variável**.</Passo>
  <Passo>Digite o nome da variável (ex.: `nome_cliente`) e escolha a operação desejada.</Passo>
  <Passo>Informe o valor — pode ser texto fixo ou uma expressão como <code v-pre>{{contact.name}}</code>.</Passo>
  <Passo>Repita para quantas variáveis precisar e salve.</Passo>
</Passos>

### Operações disponíveis

| Operação | O que faz |
|----------|-----------|
| **over-write** | Substitui o valor atual pelo novo |
| **clear** | Apaga o valor (deixa a variável vazia) |
| **append** | Adiciona texto ao final do valor existente |
| **extend** | Adiciona itens ao final de uma lista |

<Secao icon="circle-check">Exemplo</Secao>

Você quer guardar a resposta do cliente e depois mostrar numa mensagem:

```
variável: produto_escolhido
operação: over-write
valor:    {{esperar_botao.label}}
```

Depois, no nó de mensagem: <code v-pre>"Você escolheu: <span v-pre>{{produto_escolhido}}</span>. Aguarde!"</code>

<Dica>

Use nomes de variável sem espaços e sem acentos. Prefira `snake_case`, como `nome_cliente` ou `valor_total`. Fica mais fácil de usar nas expressões <code v-pre>{{ }}</code>.

</Dica>

---

## Nó Mesclar Variáveis (`variable_assigner`)

Esse nó pega valores de várias partes do fluxo e os organiza numa saída única e tipada — ideal quando você precisa passar um "pacote de dados" para um nó de IA ou de integração.

<Secao icon="list-checks">Passo a passo</Secao>

<Passos>
  <Passo>Arraste o nó **Mesclar Variáveis** para o canvas.</Passo>
  <Passo>Escolha o tipo de saída: **Texto**, **Número**, **Objeto JSON** ou **Array**.</Passo>
  <Passo>Adicione as entradas, mapeando cada campo ao valor correspondente do fluxo.</Passo>
  <Passo>Conecte a saída deste nó ao próximo bloco que vai consumir esses dados.</Passo>
</Passos>

<Secao icon="sliders-horizontal">Campos</Secao>

| Campo | O que faz |
|-------|-----------|
| **Tipo de saída** | Define o formato do resultado (texto, número, objeto, array) |
| **Entradas** | Lista de pares `chave → valor` que serão mesclados |
| **Nome da variável de saída** | Como essa variável ficará disponível nos próximos nós |

<Cuidado>

O nó `set_variable` (legado) ainda funciona, mas não recebe novas operações. Se você está montando um fluxo novo, use sempre o `assigner` — ele é mais flexível e claro.

</Cuidado>

---

## Saiba mais

- [A tela do Flow Builder](/guia/flow-builder/a-tela) — onde fica o painel de configuração e o título editável do nó