## Visão geral

Um fluxo fica muito mais poderoso quando consegue **ler os dados que o iniciaram** e **reaproveitar o
resultado de cada etapa**. O Flow Builder agora traz um conjunto de recursos de **dados e mapeamento**:
o corpo do webhook/API vira variável, a resposta de qualquer nó anterior fica disponível para os
próximos, o webhook de saída pode guardar a resposta, e dois nós novos — **Loop de itens** e
**Transformar dados** — deixam você percorrer listas e manipular dados sem sair do canvas.

Tudo é opcional e retrocompatível: fluxos existentes continuam funcionando exatamente como antes.

## Pré-requisitos

- O módulo **Flow Builder** habilitado para a sua conta.
- **Administrador** para editar e publicar o fluxo. **Agentes** podem acompanhar as execuções.
- Para os recursos de gatilho por dados: um gatilho de **Webhook** ou **API** no fluxo.
- Noção básica de **variáveis**: no editor, o botão de variáveis (`{ }`) e digitar `{{` abrem a lista de
  tokens disponíveis. Insira tokens escrevendo-os entre chaves duplas, por exemplo `{{ trigger.body.email }}`.

## Passo a passo

Exemplo: um pedido chega por webhook e você quer usar o número do pedido numa mensagem.

1. No nó de **gatilho** (Webhook ou API), abra a seção **Amostra do payload**.
2. Clique em **Buscar último evento** (ou **Colar JSON**) para trazer um exemplo real do corpo.
3. Na **árvore** que aparece, clique no valor desejado (ex.: `order.id`). Isso cria um mapeamento
   **variável ← caminho** (ex.: `id ← body.order.id`).
4. Opcional: **Fixe** a amostra para guardá-la no fluxo e alimentar a lista de variáveis do editor.
5. Em qualquer nó seguinte, use a variável mapeada (`{{ vars.id }}`) — ou vá direto ao corpo com
   `{{ trigger.body.order.id }}`.
6. Publique o fluxo.

## Configurações & opções

### Dados do gatilho

- **Corpo do webhook/API como variável**: o corpo que iniciou o fluxo fica disponível em
  `{{ trigger.body.campo }}` — por exemplo `{{ trigger.body.order.id }}` ou `{{ trigger.body.items[0].sku }}`.
  Funciona para JSON e para formulários; conteúdos não estruturados chegam em `{{ trigger.body.raw }}`.
- **Limite de tamanho**: o corpo é guardado até **64 KB**. Payloads maiores são **truncados** (os
  campos de topo são preservados e um aviso é marcado).
- **Mapeamento direto no gatilho**: além de ler o corpo, você pode mapear caminhos para **variáveis
  nomeadas** já no gatilho (variável ← caminho). Esse mapeamento vale para **todas as famílias de
  gatilho**, não só webhook — os caminhos são relativos ao dado que iniciou o fluxo.

### Amostra de payload no editor

Disponível no gatilho de **Webhook** e de **API**:

| Ação | O que faz |
| --- | --- |
| Buscar último evento | Traz a última chamada real recebida por aquele gatilho. |
| Escutando | Se ainda não houver evento, o editor fica **escutando** e verifica a cada poucos segundos (até 60s). Envie uma chamada de teste para capturá-la. |
| Colar JSON | Cole um exemplo manualmente quando ainda não há tráfego real. |
| Árvore clicável | Renderiza a amostra; **clicar** num valor cria um mapeamento variável ← caminho. |
| Fixar (pin) | Guarda a amostra no fluxo. A amostra fixada alimenta a lista de variáveis do editor e viaja junto na exportação (você pode desafixar quando quiser). |

### Painel "Dados disponíveis" no inspetor

Ao selecionar qualquer nó, o inspetor mostra o painel **Dados disponíveis** — um catálogo de tudo que
você pode inserir, organizado em quatro abas:

- **Gatilho** — a árvore do payload do gatilho (amostra fixada ou a última execução real). Clique num
  valor para inserir `{{ trigger.… }}`. Ainda sem amostra? Use **Buscar último evento**.
- **Etapas** — a saída de cada nó anterior, com os **valores reais da última execução**. Etapas sem saída
  ainda aparecem como "sem saída ainda"; etapas renomeadas ou removidas ficam esmaecidas.
- **Variáveis** — as variáveis que o fluxo produz (`vars.*`), com o valor da última execução quando houver.
- **Padrão** — os campos padrão de contato, conversa, agente, caixa, conta, CRM, fluxo e Account Brain.

Cada campo mostra, quando disponível, um **valor de exemplo** (da última execução) ao lado do token — o
mesmo aparece na lista do botão de variáveis (`{ }`). Clique num campo e ele é inserido **onde o cursor
está**. Os valores refletem a **última execução** e podem estar **desatualizados**; use **Atualizar** para
buscar a mais recente.

### Mapear campos automaticamente

Nas telas de mapeamento (teste do **HTTP request**, **amostra do gatilho** e **Webhook de saída**), quando
há uma amostra da resposta, o botão **Mapear campos automaticamente** cria uma linha para cada campo de
**primeiro nível**: o nome da variável é normalizado (minúsculas com `_`) e o caminho aponta para o campo.
Nomes repetidos ganham sufixo (`_2`, `_3`), campos já mapeados são ignorados e o limite é de 20 por clique.
O campo de **caminho** também sugere os caminhos da amostra enquanto você digita.

### Inserir variáveis nas ações

Os nós de **ação** (criar contato, ações de CRM, tarefas, WhatsApp, etc.) agora também oferecem o botão de
variáveis. Digitar `{{` num campo de texto abre a lista, e o cabeçalho traz **Inserir variável** para as
ações compostas só de seletores. A variável entra no campo em foco, exatamente como nas mensagens.

### Saídas por etapa

- A resposta de **qualquer nó anterior** fica disponível para os próximos em
  `{{ steps.nome_da_etapa.campo }}`.
- O **nome da etapa** é o rótulo do nó em **minúsculas com `_`** no lugar de espaços/símbolos (ou o id
  do nó, quando o rótulo estiver vazio). Renomeie o nó para ter um nome previsível.
- Campos comuns: `status` em qualquer nó; o nó de **requisição HTTP** também expõe `body` e `handle`
  (ex.: `{{ steps.consulta.body.total }}`, `{{ steps.consulta.status }}`).

### Webhook de saída: capturar a resposta

- O nó **Webhook de saída** pode, opcionalmente, **guardar a resposta** numa variável e mapear campos
  dela para variáveis nomeadas (caminhos com ponto, ex.: `data.id`).
- É **desligado por padrão**: sem variável e sem mapeamentos, o comportamento é idêntico ao de antes.

### Novos nós: Loop de itens e Transformar dados

**Loop de itens** — percorre uma lista **um item por vez**:

- Aponte a **lista** (ex.: `{{ vars.orders }}`, `{{ steps.consulta.body }}` ou um caminho com ponto).
- Cada passagem expõe o **item atual** e o **índice** em variáveis (ex.: `{{ vars.item }}`,
  `{{ vars.loop_index }}`).
- Ligue a saída **item** de volta ao nó para repetir; a saída **concluído** dispara ao fim.
- Limites: até **100 itens** por laço; cada passagem consome os passos do corpo dentro do **limite de
  passos da sessão** (por isso laços muito grandes podem esgotar o orçamento — o editor avisa).

**Transformar dados** — manipula dados e grava numa variável, com saídas **sucesso** / **erro**:

- **Template**: gera texto a partir de um modelo.
- **JSON**: gera dados estruturados (o texto precisa ser um JSON válido).
- **Operação de lista**: aplica **uma** operação sobre uma lista — `pick`, `filter`, `first`, `last`,
  `count`, `sum`, `unique`, `sort`, `join`.
- **Texto**: divide texto em uma lista ou extrai valores com uma expressão regular.

## Casos de uso

- Transformar um pedido recebido por webhook em contato, negócio, cobrança e tarefa encadeados.
- Percorrer itens de uma resposta HTTP e executar uma ação controlada para cada item.
- Mapear IDs e status de provedores para esperas, condições e mensagens posteriores.

### Mapeamento em escala (payloads grandes e aninhados)

O mapeamento foi reforçado para payloads reais — grandes, profundos e cheios de objetos aninhados:

- **Mapear campos automaticamente** agora desce até **6 níveis** e mapeia todas as folhas (objetos como
  `utm{}` e `contact{}` incluídos), com nomes derivados do último segmento (`utm.utm_source` →
  `utm_source`) e desambiguação automática em colisões (`contact.id` e `order.id` → `id` e `order_id`).
  Quando há mais campos do que o limite de 100 por clique, o aviso diz exatamente **"Mapeados X de Y"**.
- **Busca em tudo**: o seletor de variáveis e o painel de dados ganharam busca — inclusive por campos
  além do limite de exibição (o rodapé mostra quantos ficaram ocultos).
- **Árvores gigantes sob controle**: cada ramo mostra 50 itens por vez ("Mostrar mais 50"), com badge
  de tamanho (`~N KB`), copiar caminho/valor no hover e navegação por TODOS os índices de um array
  (dá para mapear `items.3.sku`, não só o primeiro item).
- **Nada some em silêncio**: quando o servidor precisa podar uma resposta muito grande, os ramos
  removidos aparecem em um banner âmbar (com os caminhos exatos); um caminho mapeado que não existe no
  payload vira um chip "caminho não encontrado" no rastreio — a variável fica vazia, mas você fica
  sabendo.
- **Índice negativo**: `items.-1.sku` pega o **último** item da lista. A forma com colchetes
  (`items[0].sku`) também é aceita ao digitar e é convertida automaticamente.
- **Condições mais ricas**: 14 operadores novos (termina com, está na lista, está vazio, é número,
  é verdadeiro/falso, datas antes/depois/dentro de N dias, tamanho maior/menor, lista contém) e
  **grupos de condições** com TODAS/QUALQUER entre grupos.
- **Transformar dados** ganhou operações novas (mínimo, máximo, média, fatiar, inverter, achatar,
  compactar, para JSON) e o modo **texto** (dividir em lista e extrair com regex).

## Dicas, limites e boas práticas

- **Sem ramos paralelos**: o fluxo anda **um passo por vez** — não há execução simultânea de dois
  caminhos nem nós de junção. O **Loop de itens** processa a lista em sequência (o que também deixa
  esperas dentro do laço funcionarem naturalmente).
- **Payloads grandes são truncados**: o corpo do gatilho (64 KB) e as saídas por etapa têm limites; ao
  ultrapassá-los, o dado é truncado e um aviso é marcado para você perceber.

## Solução de problemas

- **Caminho não encontrado:** atualize a amostra e confirme o caminho completo, inclusive índices de arrays.
- **Saída ausente:** verifique se a etapa executou e se o trace marcou truncamento ou remoção.
- **Publicação recusada:** corrija a variável, o handle ou o campo fora do schema apontado pela validação.
- **Modo de transformação não suportado:** escolha Template, JSON, Lista ou Texto. O erro da
  execução mostra o valor recebido e os identificadores válidos: `template`, `json`, `array`, `string`.

## Veja também

- [Flow Builder: construir fluxos conversacionais visualmente](/hc/ajuda/articles/automation-flows-flow-builder-pt-br)
- [Flow Builder: ações nativas e nó de ação de contato](/hc/ajuda/articles/automation-flows-flow-builder-acoes-nativas-pt-br)
- [Flow Builder na prática: sessões, versões, relatórios e conexões de banco](/hc/ajuda/articles/automation-flows-flow-builder-operacao-pt-br)
- [Regras de automação: gatilhos, condições e ações](/hc/ajuda/articles/automation-flows-regras-de-automacao-pt-br)