Tema
Variáveis · set_variable / assigner / variable_assigner
Referência do nó
Kind
assigner / set_variable / variable_assignerCategoriaDadosPara que serve
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.
Quando usar
- 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 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...).
Exemplo
Um nó Agente de IA renomeado para "Consulta CPF" tem sua saída referenciada assim:
{{consulta_cpf.resposta}}Em vez do antigo {{n_agent_1722538_3.resposta}} — muito mais fácil de ler e de manter conforme o fluxo cresce.
Quando a saída do nó é um objeto (JSON), o caminho pode descer quantos níveis forem necessários — sempre pontuado, id_do_nó.campo.subcampo.... Um nó Ferramenta MCP com id mcp cuja ferramenta devolve {"result": {"data": "<conteúdo>"}} é referenciado assim:
{{mcp.result.data}}Dica
Renomear é seguro: todas as referências existentes no fluxo — templates {{ }}, expressões, condições e os ponteiros de conexão entre nós — são reescritas automaticamente para o novo nome. Nada quebra.
Atenção
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.
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 naquele canal; 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ó, junto com as saídas dos nós anteriores, Sistema (sys.), Evento (event.) e Contato.
O seletor de variáveis
O botão de chaves {} na barra de qualquer campo de texto abre o seletor. Ele é dividido em duas colunas: à esquerda a lista de fontes, à direita os campos da fonte escolhida.
As fontes vêm agrupadas em quatro faixas:
| Faixa | O que traz |
|---|---|
| Nós do fluxo | Uma entrada por nó anterior, com as saídas que ele produz |
| Deste fluxo | Fluxo, Local e Gatilho — o que vive só nesta execução |
| Do cadastro | Contato, Campos Personalizados, Workspace e Sistema — o que atravessa execuções |
| Do atendimento | Conversa, Atendente e Data/Hora — o mesmo catálogo das respostas rápidas |
Ao lado de cada nó há um ponto verde quando ele guardou valores da última execução, e um contorno vazio quando ainda não rodou.
Cada campo mostra o valor que teve
À direita de cada campo aparece o valor da última execução. Quando o nó ainda não rodou, no lugar do valor vem o tipo esperado (texto, número, lista, objeto). É a forma rápida de responder "essa variável vai chegar preenchida?" antes de publicar o fluxo.
O rodapé do seletor é a faixa de inspeção: mostra a referência exata pronta para copiar e o valor inteiro do campo sob o cursor, sem cortar. Serve justamente para os campos longos, como a transcrição de um áudio, em que a prévia da lista não cabe.
Buscar e navegar pelo teclado
A busca no topo cobre todas as fontes de uma vez, e procura tanto pelo nome amigável quanto pelo caminho completo — digitar Primeiro acha contact.first_name. Enquanto você busca, a coluna da esquerda mostra só as fontes que têm resultado, com a contagem de cada uma.
Pelo teclado: ↑ ↓ percorrem a lista, → e ← abrem e fecham um objeto, Enter insere e Esc fecha.
Dica
Campos do contato aparecem com o nome amigável e a chave real lado a lado — Primeiro Nome first_name. O nome ajuda a achar; a chave é o que vai para a mensagem.
Quando a estrutura interna do campo não é conhecida
Um campo do tipo objeto (ex.: o result de uma Ferramenta MCP) só aparece expansível no seletor quando o Flow Builder já sabe o que tem dentro dele — pela última execução do nó, ou pelo schema que o próprio servidor MCP declarou para a ferramenta. Sem nenhuma das duas coisas, o campo aparece "fechado": não dá pra abrir e escolher um subcampo pelo clique.
Nesse caso a faixa de inspeção, no rodapé do seletor, ganha um campo de texto onde você completa o caminho à mão — digite só a parte que falta (ex.: data) e o seletor final vira {{mcp.result.data}}, pronto para inserir ou copiar.
Atenção
Complete o caminho só quando você tem certeza do formato real da resposta (documentação da ferramenta, teste manual fora do fluxo). Um caminho inventado não dá erro nenhum ao publicar — ele só volta vazio quando o fluxo roda, porque o motor de execução resolve {{...}} em runtime, sem checar se o campo existe.
Campo personalizado não fica em contact.
Campos Personalizados é uma fonte separada de Contato, e essa separação é real: o campo personalizado do contato vive em custom_fields., nunca em contact..
Atenção
{{contact.data_pericia}} não interpola o campo personalizado "Data Pericia". contact. guarda os dados do cadastro (nome, e-mail, telefone) e as variáveis de contato que você declarou no Gerenciador — o campo personalizado não está lá. O certo é {{custom_fields.data-pericia}}.
O erro não aparece ao publicar: o motor de execução resolve {{...}} só na hora do envio e, sem achar o campo, escreve vazio. A mensagem sai para o contato com um buraco no lugar da data.
A chave do campo personalizado é o slug, gerado a partir do nome quando o campo foi criado: "Data Pericia" vira data-pericia, "Horário da Reunião" vira horario-da-reuniao. Repare que o separador é o hífen, não o sublinhado. Não tente adivinhar o slug — abra o seletor de variáveis e escolha o campo na fonte Campos Personalizados, que insere a referência certa.
As variáveis do atendimento dentro de um fluxo
A faixa Do atendimento traz o mesmo vocabulário das respostas rápidas, e ele funciona dentro do fluxo:
| Prefixo | Dentro de um fluxo |
|---|---|
contact. | Preenchido |
flow. local. event. sys. | Preenchidos |
conversation. | Preenchido: conversation.id (protocolo), conversation.status e conversation.channel |
agent. | Preenchido com o atendente atribuído à conversa |
custom_fields. | Preenchido pelo slug do campo personalizado do contato — nunca por contact. |
date. | Calculado no momento do envio, no fuso do workspace |
workspace. | Só as variáveis que você declarou no Gerenciador. workspace.name, workspace.city e workspace.state são do cadastro da empresa e continuam não preenchidos |
Dica
Campo personalizado do tipo Data ou Data e Hora não chega como texto ISO cru (ex.: 2026-11-16T22:00:00.000Z) — o Flow Builder formata no padrão brasileiro. Data e Hora vira dd/mm/aaaa hh:mm, já convertido para o fuso do workspace (ex.: 16/11/2026 19:00); Data vira só dd/mm/aaaa, sem conversão de fuso — uma data pura não tem hora para converter, e converter mudaria o dia em alguns fusos. A mesma regra vale nas respostas rápidas e no composer do atendimento.
O que ainda não é preenchido aparece marcado no seletor: a etiqueta não resolve no fluxo no topo do painel, ou só no atendimento na linha específica quando a fonte é mista.
Dica
date. é calculado na hora do envio, não no disparo. Um fluxo que espera dois dias pela resposta do contato e só então manda a mensagem escreve a data de hoje, não a de anteontem.
Atenção
conversation. e agent. dependem de o fluxo ter nascido de uma conversa — mensagem recebida, evento de conversa. Num fluxo agendado ou disparado por webhook não existe conversa, e essas variáveis vêm vazias.
agent. é o atendente humano atribuído à conversa. Numa conversa em automação, sem ninguém atribuído, vem vazio — isso é o esperado, não um defeito. Para identificar o agente de IA que respondeu, use as saídas do próprio nó de agente.
O que cada gatilho entrega
O que chega preenchido depende do que o gatilho conhece. Um gatilho que nasce de uma conversa entrega tudo; um agendado não tem contato nem conversa para entregar.
| Gatilho | custom_fields. | conversation. agent. | date. |
|---|---|---|---|
| Mensagem recebida / evento de conversa | sim | sim | sim |
| Disparo manual (botão na conversa, follow-up) | sim | sim | sim |
| Campo do contato alterado | sim | parcial¹ | sim |
| Data do contato | sim | parcial¹ | sim |
| Formulário respondido | sim | não | sim |
| Webhook | não² | não | sim |
| Agendado | não² | não | sim |
¹ Só conversation.id, quando o contato já tem uma conversa. Não há mensagem que preencha status, canal ou atendente.
² Esses gatilhos não têm contato, então não existe campo personalizado a resolver. Se o fluxo precisa deles, busque o contato num nó antes de montar a mensagem.
Dica
Até setembro de 2026 só o gatilho de evento preenchia custom_fields. e o fuso de date.. Se você tem um fluxo antigo em que {{custom_fields.algum-campo}} saía em branco, ele volta a funcionar sozinho — não precisa reescrever a mensagem.
Para referenciar uma variável numa expressão, use a notação pontuada com o prefixo do escopo: {{flow.nome_lead}}, {{contact.email}}.
Atenção
A referência precisa do ponto do escopo. {{flow.x}} funciona, mas {{x}} sozinho — sem escopo — não é interpolado e fica literal na mensagem.
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.
Atenção
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.
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
0numa variável do tipo Número vira o número zero (não o texto"0"), efalsenuma variável Booleano vira falso de verdade — então dá para usar direto numa condição sem conversão.
Atenção
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.
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.
Atenção
As variáveis de contato são separadas por canal. Se o mesmo contato fala com a sua empresa em dois canais diferentes, cada canal tem seu próprio conjunto de variáveis contact. — o que um fluxo do canal A gravou não aparece num fluxo do canal B, mesmo sendo a mesma pessoa. Isso evita que dados coletados num atendimento vazem para outro.
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.
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.
Atenção
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).
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 |
|---|---|---|
{{event.contact.is_client}} | Booleano | Verdadeiro quando o contato já está cadastrado como cliente no sistema jurídico conectado ao workspace |
{{event.contact.legal_provider}} | 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.
Gatilhos de campanha: event.campaign.*
Os gatilhos de campanha (Lead de anúncio CTWA, Formulário de Lead Ads e WhatsApp Flow concluído) entregam o bloco event.campaign com a campanha de origem, além de event.campaign_id, event.campaign_lead_id e event.contact_id.
| Variável | O que contém |
|---|---|
event.campaign.id / event.campaign.name | Id interno e nome da campanha |
event.campaign.source_type | Origem: ctwa, lead_form ou whatsapp_flow |
event.campaign.platform | facebook, instagram ou whatsapp |
event.campaign.external_id | Id do anúncio, do formulário ou template do Flow |
event.campaign.ad_id / event.campaign.ad_name | Id e nome do anúncio na Meta (podem vir vazios) |
event.campaign.campaign_name | Nome da campanha na Meta (Lead Ads, ou CTWA com Contas de Anúncios conectadas; pode vir vazio no primeiro lead de um anúncio novo) |
Cada gatilho traz ainda campos próprios (event.referral.*, event.form_id, event.fields.*, event.flow_token, event.conversation_id). Veja a lista completa em Lead de Anúncio (CTWA), Formulário de Lead Ads e WhatsApp Flow Concluído.
Etiquetas do contato: contact.tags
O contato expõe também contact.tags: uma lista de textos com o nome de cada etiqueta atribuída a ele (ex.: ["Cliente", "VIP"]). O nome de cada etiqueta é o mesmo texto configurado no cadastro de etiquetas do workspace.
Quando o contato não tem nenhuma etiqueta, contact.tags vem como lista vazia — nunca ausente — então uma condição sobre ela nunca quebra por falta da variável.
Exemplo
Num nó Se / Senão (condição), configure a condição:
variável: contact.tags
operador: contém
valor: ClienteIsso bifurca o fluxo para quem já tem a etiqueta "Cliente" atribuída.
Dica
contact.tags é sempre lista de nomes (texto), não de objetos — assim ele funciona direto com os operadores contém, não contém, contém todos e contém algum do Se/Senão, sem precisar de sub-condição de variável.
Nó Atribuir Variável (assigner)
Passo a passo
- Arraste o nó **Atribuir Variável** para o canvas e conecte-o ao bloco anterior.
Paleta de nós aberta no canvas do Flow Builder, com as categorias disponíveis para localizar e arrastar o nó desejado
- No painel à direita, clique em **+ Adicionar variável**.
Painel de configuração do nó Atribuidor, com a seção Variáveis vazia e o toggle Transacional (tudo-ou-nada)
- Digite o nome da variável (ex.: `nome_cliente`) e escolha a operação desejada.
- Informe o valor — pode ser texto fixo ou uma expressão como
{{contact.name}}. - Repita para quantas variáveis precisar e salve.
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 |
Exemplo
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: "Você escolheu: {{produto_escolhido}}. Aguarde!"
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 {{ }}.
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.
Passo a passo
- Arraste o nó **Mesclar Variáveis** para o canvas.
- Escolha o tipo de saída: **Texto**, **Número**, **Objeto JSON** ou **Array**.
- Adicione as entradas, mapeando cada campo ao valor correspondente do fluxo.
- Conecte a saída deste nó ao próximo bloco que vai consumir esses dados.
Campos
| 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 |
Atenção
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.
Saiba mais
- A tela do Flow Builder — onde fica o painel de configuração e o título editável do nó