## 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** →
4. **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](/hc/ajuda/articles/automation-flows-flow-builder-dados-e-mapeamento-pt-br)
- [Flow Builder: ações nativas](/hc/ajuda/articles/automation-flows-flow-builder-acoes-nativas-pt-br)
- [Flow Builder na prática](/hc/ajuda/articles/automation-flows-flow-builder-operacao-pt-br)