Flow Builder: formulários de ação e listas de eventos e ações por categoria

Visão geral

Algumas ações nativas fazem muito mais do que definir um único valor — criar um negócio do CRM, uma cobrança, uma tarefa, um contato ou uma conversa envolve vários campos. Agora essas ações mostram um formulário de verdade no nó de ação do Flow Builder, no lugar do seletor de valor único. Você preenche cada campo com os mesmos campos tipados usados no restante do construtor, incluindo o seletor de {{ variável }}.

Ao mesmo tempo, as longas listas de eventos e ações agora são agrupadas por módulo e têm busca, então você encontra crm_item_won ou "Criar negócio" sem rolar tudo.

Pré-requisitos

• Permissão de Admin para editar automações, macros, fluxos e webhooks.
• O módulo correspondente ativo na conta (CRM, Pagamentos, Tarefas, Follow-ups, …) para preencher seus seletores.

Passo a passo

1. Abra um fluxo, adicione um nó de Ações gerais e escolha a ação.
2. Preencha primeiro os campos dos quais outros dependem, como funil → etapa.
3. Use { } para inserir variáveis e Avançado para alvos, vínculos e atributos.
4. Rode Executar teste com o contexto correto e revise saída, skips e efeitos antes de publicar.

Configurações & opções

Formulários de ação (orientados a parâmetros)

Ao escolher uma destas ações em um nó de Ações gerais, aparece um formulário com exatamente os campos que a ação aceita:

• Criar negócio do CRM — título, descrição, funil → etapa (a lista de etapas segue o funil escolhido), valor (com variáveis), moeda, prioridade, responsável, time, data prevista de fechamento, data de abertura, contato (por id, e-mail ou telefone), empresa, participantes (colaboradores do negócio) e os atributos personalizados e adicionais.
• Criar cobrança — tipo de cobrança, valor (com variáveis), moeda, descrição, vencimento, parcelas (para cartão de crédito) e, em Avançado, a conexão de pagamento, o vínculo com o negócio, os produtos do catálogo e a origem.
• Criar tarefa — título, descrição, responsável, prioridade, status, data de vencimento ou "vence em N dias", a lista de tarefas e, em Avançado, o time, a tarefa-pai, a data de início, as etiquetas e os atributos personalizados e adicionais.
• Criar um agendamento — calendário, título, descrição, local, fuso, início e fim, dia inteiro, conferência, convidados, recorrência e, em Avançado, o contato explícito, o vínculo com um negócio e com uma tarefa, além dos atributos personalizados e adicionais.
• Criar contato / Criar conversa — os campos de identidade (nome, e-mail, telefone, identificador), caixa de entrada, atributos personalizados; e, para conversas, o status inicial, responsável, time e mensagem.
• Inscrever em follow-up — a sequência e, opcionalmente, os vínculos com negócio/cobrança em Avançado.
• Criar assinatura — tipo de cobrança, valor, moeda, ciclo (semanal a anual), descrição, primeiro vencimento e, em Avançado, a conexão de pagamento e o plano.
• Enviar template do WhatsApp — nome, idioma e variáveis do template aprovado no Meta, com namespace e texto de fallback em Avançado.
• Verbos de encadeamento — adicionar nota/checklist/participante, atribuir negócio ou tarefa, comentar/etiquetar/vincular tarefa, enviar/cancelar cobrança ou assinatura, assumir conversa e ajustar orçamento de anúncio ganharam formulários com um campo de alvo explícito em Avançado (veja "Encadeando passos" abaixo).

Dois detalhes importantes:

• O dinheiro é escrito em unidades principais e aceita variáveis. 4,97 significa R$ 4,97; você também pode digitar um token como {{ crm.value }}, que é renderizado quando o fluxo executa.
• O seletor funil → etapa é dependente: escolher outro funil limpa a etapa, para você nunca manter uma etapa que pertence a outro funil.

Os mesmos formulários nas Automações e nas Macros

Estes formulários deixaram de ser exclusivos do Flow Builder. Criar negócio do CRM, Criar tarefa, Criar um agendamento, Criar contato, Vincular tarefa a um registro, Definir time da tarefa e Registrar pedido mostram o formulário completo também no editor de Automações e no de Macros — antes, "Criar um negócio no CRM" pedia ali apenas título e descrição, sem funil, etapa, valor nem responsável.

As demais ações continuam exatamente como estavam: as que já têm um editor dedicado (valor do negócio, atributo personalizado, catálogo, pagamentos, comércio, WhatsApp…) mantêm o widget rico delas.

Alguns campos aparecem só no Flow Builder: os que existem para encadear passos (o contato e a empresa de "Criar negócio", a tarefa-pai de "Criar tarefa"). Numa regra que dispara por conversa esses campos fixariam todas as execuções no mesmo registro — deixando-os em branco, a ação usa o contato da conversa que disparou, que é o comportamento correto.

Nada de digitar id: seletores buscáveis e data com calendário

Todo campo que antes pedia um id cru virou um seletor buscável de registros de verdade — negócio, tarefa, contato, empresa, lista de tarefas, agenda, cobrança, assinatura, plano, afiliado e campanha de anúncio. Cada campo traz um botão para alternar entre:

• Escolher — busca pelo nome (ou título) e mostra os registros da conta;
• Variável — o campo de texto com o seletor de {{ }}, para encadear {{ steps.criar_negocio.id }}.

O modo é deduzido do próprio valor: um valor com {{ já abre no modo variável. Trocar de modo não apaga o que estava configurado, e um id salvo cujo registro não veio na primeira página continua aparecendo como #123 em vez de sumir. A lista só é carregada quando você abre o seletor.

Datas de negócio (início e fim de um agendamento, data de abertura de um negócio) usam agora o seletor de data e hora no fuso da conta — o mesmo componente do resto do produto —, também com o modo variável ao lado. Campos de dia puro (vencimento, data prevista de fechamento) seguem como data simples.

"Vincular tarefa a um registro" ficou completo: além do tipo (Conversa, Contato, Negócio), agora tem o seletor do registro alvo, que acompanha o tipo escolhido. Sem esse alvo a ação não fazia nada.

Duas ações que ganharam tela

• Definir time da tarefa — escolhe o time da tarefa; em branco, remove o time atual.
• Registrar pedido — registra um pedido para o contato da conversa: título, valor, moeda, status, origem/gateway, id externo e, em Avançado, o vínculo com um negócio e o afiliado. Aparece apenas nas contas com o módulo Registro de pedidos ativo. Pedidos são deduplicados pelo id externo.

Vínculos: quem é o dono do registro criado

Quando o fluxo roda dentro de uma conversa, o negócio criado herda automaticamente a conversa e o contato dela — é o comportamento clássico de "conversa resolvida → criar negócio", e ele continua valendo quando você não preenche nada.

O que você preenche vence essa herança. Se o formulário informa um contato, é esse contato que entra no negócio, mesmo que a conversa aponte para outra pessoa. A herança passa a ser apenas um padrão para quando o fluxo não disse de quem o registro é.

Em um fluxo sem conversa (gatilho de webhook, API, agendamento), não há de quem herdar. Para esses casos o formulário aceita três caminhos, nesta ordem:

1. Contato — o id de um contato existente, normalmente vindo de um passo anterior.
2. E-mail do contato — procura pelo e-mail e, se ninguém for encontrado, cria a pessoa.
3. Telefone do contato — mesma regra, com o número normalizado para o padrão internacional (pode enviar 21971532700; ele vira +5521971532700).

Se a pessoa não puder ser resolvida nem criada (um e-mail inválido, por exemplo), o negócio ainda é criado — apenas sem o vínculo — e o motivo aparece como selo de "pulado" no painel de dados. Perder o vínculo é ruim; perder o negócio seria pior.

Atributos personalizados seguem os campos do funil

Atenção a esta regra, ela costuma surpreender: se o funil de destino tem campos personalizados configurados, o negócio guarda somente os atributos que estão nessa lista. Qualquer chave que você mande e que não esteja configurada como campo daquele funil é descartada em silêncio — sem erro, sem aviso, sem o nó falhar.

• Antes de mapear um atributo no formulário, confira em CRM → Configurações se ele existe como campo do funil que a ação vai usar.
• Se o funil não configura nenhum campo personalizado, tudo o que você mandar é guardado.
• Campos obrigatórios do funil continuam obrigatórios: mandar um deles em branco faz a criação falhar (e o nó registra o erro), em vez de gravar pela metade.

Listas por categoria e com busca

• Eventos de webhook (Configurações → Integrações → Webhooks): os eventos são agrupados por módulo (Conversas & Contatos, CRM — Negócios, Tarefas, Pagamentos, WhatsApp, …). Cada grupo tem uma busca, um seletor marcar todos com contador e um estado parcial (indeterminado) quando só alguns eventos do grupo estão marcados.
• Gatilhos das automações: o seletor de evento é dividido em seções por módulo.
• Ações (Automações, Macros e Flow Builder): o seletor de ação mostra um cabeçalho de módulo acima de cada conjunto de ações.

Nada disso muda os dados salvos — as chaves de evento, os nomes das ações e o payload do webhook continuam exatamente iguais. Só a forma de apresentar mudou.

Executar teste direto do editor

O botão Executar teste roda o rascunho atual do fluxo uma vez, sem publicar. Depois da execução, cada nó do canvas mostra um selo com o resultado (✓ concluído com a duração, ✗ falhou com o erro, ◇ pulado) e o painel de dados passa a exibir os valores reais produzidos por cada etapa.

• Atenção: o teste executa as ações de verdade — cria registros, dispara cobranças e webhooks. Uma confirmação explícita aparece antes de rodar.
• Sem uma conversa de teste, os nós de mensagem são pulados (o restante do fluxo roda normalmente). Você pode informar uma conversa ou um contato para testar o caminho completo.
• Disponível para administradores.

Gatilho de webhook: autenticação flexível e teste antes de publicar

• O endereço e o token do webhook já existem desde o rascunho — o exemplo de curl do painel é real desde o primeiro salvamento.
• Um envio autenticado para um fluxo não publicado é aceito como amostra de teste (o painel captura o corpo para o mapeamento), sem iniciar uma sessão. Publique quando estiver pronto.
• Três modos de autenticação: Assinado (HMAC do corpo — padrão e mais seguro), Bearer (cabeçalho Authorization) e Segredo na URL (?token=…) — os dois últimos para ferramentas que não assinam o corpo (formulários, ERPs, no-code).
• O painel mostra a última entrega recebida (aceita, amostra capturada, repetida ou rejeitada por autenticação) com horário — nada de adivinhar se o POST chegou.

Encadeando passos (ids de registros criados)

Cada ação que cria um registro agora expõe o id (e os principais campos) na saída do passo. No seletor de variáveis, procure pelo nome do nó — por exemplo, um passo "Criar negócio" oferece o id para os passos seguintes usarem como alvo:

1. Receber lead (gatilho de webhook) → 2. Criar contato → 3. Criar negócio do CRM →
2. Criar cobrança → 5. Inscrever em follow-up → 6. Criar tarefa.

A chave do passo é o nome do nó em minúsculas, com _ no lugar de tudo que não for letra sem acento, número ou _. Um nó chamado "Buscar contato" vira buscar_contato, e a saída dele é lida assim:

• {{ steps.buscar_contato.contact_id }} — o contato encontrado, pronto para ir no campo Contato de um "Criar negócio do CRM" logo em seguida.
• {{ steps.criar_venda.id }} — o negócio recém-criado por um nó chamado "Criar venda", para vincular uma cobrança, um agendamento ou uma tarefa a ele.
• {{ steps.criar_tarefa.id }} — a tarefa criada, útil como tarefa-pai de subtarefas ou como vínculo de um agendamento.

Cuidado com acentos e cedilha: eles não viram a letra sem acento, viram _. Um nó "Criar negócio" responde por criar_neg_cio, e "Criar cobrança" por criar_cobran_a. Por isso vale nomear os nós que você pretende encadear sem acentos — ou simplesmente escolher o token no seletor de variáveis.

Renomeou o nó? A chave acompanha o nome novo — reveja os tokens que apontavam para ele. Se dois nós tiverem exatamente o mesmo nome, o primeiro fica com a chave e o outro passa a responder pelo id do nó (o seletor de variáveis sempre mostra o token correto, então prefira escolher por lá a digitar de cabeça).

• Em um fluxo sem conversa (webhook/API), o contato criado no passo 2 vira automaticamente o alvo dos passos seguintes.
• Os formulários de nota, checklist, participante, atribuição, comentário, etiqueta e vínculo têm um campo de alvo em Avançado que aceita o id de um passo anterior; vazio, valem os alvos do próprio fluxo.

Quando uma ação não faz nada: motivo no painel e modo estrito

Algumas ações simplesmente não têm o que fazer — não havia negócio para atribuir, o contato não pôde ser resolvido, o módulo não estava configurado. Antes isso passava despercebido: o fluxo seguia adiante, o passo terminava vazio e nada explicava o porquê.

Agora a ação que decide não agir registra o motivo junto do passo. Para consultar:

1. Abra o painel Dados disponíveis e vá até a aba Etapas.
2. O passo exibe o aviso "Ação ignorada" seguido do motivo, no mesmo bloco de alertas dos avisos de truncamento.
3. Com o passo recolhido, o ícone de atenção no cabeçalho já traz o motivo na dica de tela — não é preciso expandir para entender o que aconteceu.

Vale tanto para o Executar teste quanto para o histórico de execuções.

Por padrão uma ação ignorada não interrompe o fluxo: ela é registrada e a execução continua. Use esse aviso justamente para descobrir por que um passo seguinte não encontrou o registro que esperava.

Modo estrito: parar em vez de seguir com um registro pela metade

Quando seguir adiante é pior do que parar, abra Avançado no nó de ação e ligue a chave "Falhar o nó quando a ação não fizer nada":

• Desligada (padrão) — comportamento de hoje, sem mudança nenhuma nos fluxos existentes: quando a ação deixa de agir, o fluxo segue em frente e o motivo aparece na saída da etapa.
• Ligada — a ação que deixa de agir e não produz nada faz o nó falhar, em vez de avançar. Use em etapas críticas, como a cobrança que precisa existir antes de enviar o link de pagamento.

Atenção à exceção, que é sutil: um sucesso parcial continua avançando mesmo com a chave ligada — por exemplo, o contato foi criado mas não pôde ser vinculado à caixa de entrada (o canal da caixa escolhida não conseguiu derivar um source_id). O contato existe e as próximas etapas já têm um registro real para usar, então parar ali seria errado. A chave só barra o caso em que a ação não produziu absolutamente nada.

A opção aparece em Avançado no nó genérico de Ações gerais e em todos os nós de ação por módulo: CRM, Tarefas, Contatos, WhatsApp, Agenda, Pagamentos, Catálogo, Commerce e Anúncios. O nó do Account Brain roda em um motor próprio e, por isso, não traz a chave.

Enviar modelo e enviar flow do WhatsApp

As duas ações de mensagem do WhatsApp existiam no motor, mas não apareciam em nenhum seletor — não era possível criar uma regra ou macro com elas. Agora estão no catálogo de Automações, Macros e do FlowBuilder (tanto no nó genérico quanto no nó de WhatsApp), com formulário completo:

• Enviar modelo — o modelo é uma lista dos modelos aprovados da conta (nada de digitar o nome). Deixe o idioma vazio e o envio adota o idioma do próprio modelo escolhido. As variáveis preenchem os {{1}}, {{2}} do corpo.
• Em Avançado, dois campos novos cobrem os modelos que o mapa simples não alcançava: variáveis do cabeçalho (inclusive media_url + media_type para cabeçalho de mídia) e variáveis dos botões (array JSON, um objeto por botão dinâmico). Sem eles, um modelo com cabeçalho de mídia ou botão dinâmico era recusado pela Meta.
• Enviar flow — escolha o flow publicado em uma lista; o token do flow é gerado a cada envio. Dá para definir texto do botão, mensagem, cabeçalho, rodapé, modo (publicado/rascunho), tela inicial e dados iniciais.

Condições de lista e de tamanho

Na condição do FlowBuilder, o campo Valor agora acompanha o operador, não só o campo:

• está na lista / não está na lista — marque vários valores de uma vez; eles são gravados separados por vírgula, exatamente como o motor lê. Antes só dava para escolher um, o que tornava o operador equivalente a "é igual a".
• tamanho maior/menor que, data dentro de N dias, data antes/depois de — voltam a ser texto livre, porque o valor comparado é um tamanho, um número de dias ou uma data — não um valor do campo.
• array contém continua com escolha única: ele compara um item do array.

Espera com duração inválida agora é barrada na publicação

Um nó de espera com todas as unidades zeradas aguardava 1 segundo silenciosamente, e uma unidade digitada errada derrubava o nó só durante a execução. As duas situações agora aparecem como erro na publicação do fluxo. Uma unidade com variável ({{ }}) continua sendo resolvida na execução.

Listas de opções do WhatsApp

Uma lista com mais de 10 linhas, título acima de 24 caracteres ou descrição acima de 72 era recusada pelo WhatsApp e a mensagem se perdia. Agora ela é ajustada ao limite antes do envio (as linhas excedentes saem, os textos longos são cortados) e a mensagem chega.

Casos de uso

• Criar um contato, encadear seu id em um negócio e usar o id do negócio numa cobrança ou tarefa.
• Atualizar CRM e tarefas a partir de webhook/API sem fixar IDs de outra execução.
• Parar um caminho crítico quando uma ação não produzir efeito, usando o modo estrito.

Dicas, limites e boas práticas

• Deixar um campo opcional vazio simplesmente o omite — a ação usa o valor padrão.
• Prefira variáveis a valores fixos em títulos, descrições e valores, para que o mesmo fluxo se adapte a cada contato ou negócio.
• Só preencha o contato quando quiser mesmo mandar nele: em um fluxo dentro de uma conversa, deixar o campo vazio mantém o comportamento herdado da conversa, que costuma ser o correto.
• Antes de mapear atributos personalizados, confirme que eles estão configurados como campos do funil de destino — do contrário são descartados sem aviso.
• Se um passo seguinte não achou o registro esperado, procure na aba Etapas o aviso "Ação ignorada" do passo anterior — o motivo costuma estar exatamente ali.
• Ligue o modo estrito só nos nós em que "não fez nada" é um problema de verdade, e trate a saída de erro com uma notificação ou um caminho alternativo.
• Use a busca do grupo para ir direto a um evento pelo rótulo ou pela chave técnica.

Solução de problemas

• Se um seletor vier vazio, confirme o módulo, a permissão e o recurso dependente escolhido primeiro.
• Se a ação for omitida, abra o trace e leia o motivo antes de alterar os passos seguintes.
• Se a publicação recusar o node, corrija o campo indicado pelo schema; campos desconhecidos não são aceitos no runtime v2.

Veja também

• Flow Builder: dados do gatilho, mapeamento e transformação
• Flow Builder: ações nativas
• Flow Builder na prática