Flow Builder: dados do gatilho, mapeamento e transformação

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:

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
• Flow Builder: ações nativas e nó de ação de contato
• Flow Builder na prática: sessões, versões, relatórios e conexões de banco
• Regras de automação: gatilhos, condições e ações