## Visão geral

O **Flow Builder** é o construtor visual de fluxos conversacionais da ConversaLabs. Em vez de
escrever código, você monta o diálogo conectando **nós** em um canvas: uma mensagem leva a um menu de
opções, que leva a uma condição, que pode consultar uma API e seguir caminhos diferentes conforme a
resposta do contato.

É a ferramenta certa quando a automação precisa de **várias etapas e interação** — autoatendimento
por menu, qualificação de leads, agendamento, coleta de dados e integrações — algo além do alcance de
uma regra simples.

## Pré-requisitos

- O módulo **Flow Builder** habilitado para a sua conta (recurso opcional, ativado por plano/flag). Se
  não aparecer no menu, fale com um administrador.
- Permissão de administrador para criar e publicar fluxos.
- Uma caixa de entrada (por exemplo, WhatsApp) onde o fluxo será acionado.
- Para nós que dependem de outros módulos (Pagamentos, Follow-ups, CRM, Contratos), o módulo
  correspondente precisa estar ativo.

## Passo a passo

1. Abra o **Flow Builder** e crie um novo fluxo (você pode partir de um modelo da galeria).
2. Configure o **gatilho** do fluxo (o evento que o inicia) no nó de início.
3. Arraste **nós** do painel para o canvas e conecte-os para desenhar o caminho da conversa.
4. Configure cada nó no painel lateral (texto da mensagem, opções do menu, regra da condição, URL da
   requisição, etc.).
5. Use **variáveis** para guardar e reutilizar respostas do contato e dados de integrações.
6. **Teste** o fluxo (há recursos de teste de requisição e de acompanhamento de sessão) e **publique**.

## Configurações & opções

Tipos de nó mais usados:

| Nó | Para que serve |
| --- | --- |
| Mensagem de texto | Envia um texto ao contato. |
| Menu de opções | Apresenta botões ou lista para o contato escolher. |
| Mídia | Envia imagem, vídeo, áudio ou documento. |
| Condição | Segue caminhos diferentes conforme uma regra/variável. |
| Requisição HTTP | Consulta uma API externa e usa a resposta no fluxo. |
| Variação A/B | Divide o tráfego entre caminhos para testar mensagens. |
| Pagamento | Cria/envia cobrança e aguarda o pagamento (módulo Pagamentos). |
| Follow-up | Inscreve ou cancela o contato em uma sequência (módulo Follow-ups). |
| Contrato | Envia um contrato para assinatura (módulo Contratos). |
| Ação de contato | Executa ações no contato: etiqueta, nota e atributo personalizado (categoria Contatos). |
| Criar contato | Cria um contato (nome, e-mail, telefone), com deduplicação nativa. |
| Criar conversa | Abre uma conversa em uma caixa de entrada, com status e mensagem inicial opcionais. |
| Nota privada | Deixa uma nota privada na conversa (também disponível nos fluxos). |

- **Variáveis**: capture respostas e dados de API e reutilize-os em mensagens e condições.
- **Gatilho Agendamento de calendário**: inicia o fluxo quando um agendamento é criado ou muda de
  estado no módulo Agenda; o contato e a conversa vinculados ficam disponíveis quando existirem.
- **Gatilho Compromisso da agenda**: inicia o fluxo quando um **compromisso** é criado, remarcado ou
  cancelado — inclusive os criados pelo painel, pelo Maestro, por uma automação ou mudados direto no
  Google Agenda. Use este quando o compromisso **não** nasce da página pública de agendamento (que é o
  caso do gatilho acima). O status chega no fluxo, então uma **Condição** consegue separar criado de
  remarcado e de cancelado.
- **Galeria de modelos**: comece de um fluxo pronto e adapte.
- **Teste e rastreamento de sessão**: valide o comportamento antes de publicar.

### Botões e listas no WhatsApp

Os nós **Enviar botões** e **Enviar lista** chegam como mensagem interativa nativa no WhatsApp Cloud,
na Coexistência, no WhatsApp Web e na caixa híbrida unificada. Além da mensagem e dos itens, você pode
definir:

| Campo | Nó | O que aparece no WhatsApp |
| --- | --- | --- |
| Cabeçalho | Botões e lista | Título em negrito acima da mensagem, até 60 caracteres. |
| Texto do botão da lista | Lista | Texto do botão que abre a lista, até 20 caracteres. |
| Descrição | Itens da lista | Texto menor abaixo de cada item, até 72 caracteres. |
| Título da seção | Lista (Avançado) | Título acima dos itens quando a lista é aberta, até 24 caracteres. |
| Rodapé | Botões e lista (Avançado) | Texto pequeno em cinza abaixo da mensagem, até 60 caracteres. |

Todos os campos são opcionais e aceitam variáveis. Deixe o **cabeçalho** vazio para a lista chegar sem
título. Se o **texto do botão da lista** ficar vazio, usamos "Escolha um item" no idioma da conta. No
WhatsApp Web os botões sempre exibem um título: sem cabeçalho, usamos "Opções" no idioma da conta. O
**valor** de cada item identifica a opção escolhida: é o que o fluxo compara numa espera por opção. Nas
demais esperas, o fluxo recebe o título do item.

### Espera por resposta e atendimento humano

Nos nós **Aguardar resposta** e **Aguardar resposta de follow-up**, configure o tipo de entrada e as
opções válidas. Enquanto houver tentativas disponíveis, uma resposta inválida envia a **Mensagem de
resposta inválida**; se ela estiver vazia, usa a **Mensagem de reenvio**. Preencha ao menos uma delas
para orientar o contato, por exemplo: "Não entendi. Responda 1 para confirmar ou 2 para cancelar".
Reprocessar a mesma mensagem do contato não consome outra tentativa nem envia o aviso duas vezes.

Em **Atendimento humano**, o padrão é **Encerrar espera e sessão**: quando um agente envia uma
resposta pública na conversa, essa espera por resposta e a sessão são canceladas. Notas privadas,
mensagens de bots, campanhas e mensagens identificadas como automação não contam como atendimento
humano. O cancelamento não envia mensagem, não reabre a conversa e não muda sua atribuição. Uma resposta posterior do contato
não retoma a sessão cancelada nem executa suas próximas etapas. No histórico da sessão, a saída do
nó registra o motivo `human_takeover` e o gatilho `agent_message`.

As sessões do mesmo fluxo que já estavam na fila dessa conversa também são canceladas, com o
mesmo motivo no histórico. Elas não começam depois para responder por cima do agente.

Uma macro enviada manualmente por um agente e um rascunho de follow-up aprovado por ele contam
como resposta humana. Uma entrega de mensagem agendada não conta, mesmo que o agendamento use
um agente como remetente ou seja antecipado pela ação de enviar agora. Uma cópia imediata fora da
entrega agendada conta quando usa o usuário do agente. O link de reunião enviado automaticamente
pela Agenda não conta.

**Esse padrão também vale para fluxos já publicados que não têm o campo configurado.** Para manter
a espera mesmo depois de uma resposta do agente, escolha **Manter espera** no nó e publique uma nova
versão. A escolha é registrada quando a espera começa; editar o nó não modifica esperas que já
começaram. Essa regra não altera **Aguardar até** nem esperas de evento.

Resolver a conversa sem responder **não encerra a espera**: o fluxo ainda pode consumir a próxima
mensagem do contato. Envie uma resposta pública antes de resolver **ou cancele a sessão pela tela de
sessões**. Uma resolução automática também não cancela essa espera.

Uma integração ou ferramenta MCP que envia uma resposta pública usando o usuário de um agente
conta como atendimento humano e encerra a espera. Para manter o comportamento anterior nesse caso,
selecione **Manter espera** no nó. Atendimento pelo aparelho ou eco de uma mensagem externa sem
usuário de agente identificado não encerra a espera por essa regra; o eco também pode confirmar uma
mensagem que a própria plataforma enviou.

## Casos de uso

- **Autoatendimento por menu**: o contato escolhe um assunto e é direcionado ao time certo.
- **Qualificação de leads**: perguntas em sequência que gravam respostas em variáveis e no CRM.
- **Agendamento e cobrança**: coletar dados, criar uma cobrança e confirmar após o pagamento.
- **Integração**: consultar um pedido por uma requisição HTTP e responder o status ao cliente.

## Dicas, limites e boas práticas

- Desenhe o fluxo no papel antes de montar — mapeie os caminhos e os pontos de saída.
- Sempre ofereça uma saída para **falar com um humano**; nem tudo deve ficar no automático.
- Teste cada caminho, inclusive as respostas inesperadas do contato.
- Cuidado com loops e com mensagens em excesso (boas práticas anti-ban do WhatsApp).
- Mantenha os fluxos curtos e objetivos — divida fluxos muito grandes em partes reaproveitáveis.

## Solução de problemas

- **Não vejo o Flow Builder**: o módulo pode não estar habilitado para a conta ou para o seu perfil.
- **O fluxo não inicia**: confira o gatilho e se o fluxo está publicado e vinculado à caixa de entrada certa.
- **O fluxo parou no meio**: provavelmente há um nó sem caminho de saída para a resposta recebida —
  cubra todas as opções e adicione um caminho padrão.
- **A requisição HTTP falhou**: use o testador de requisição para checar URL, cabeçalhos e resposta.
- **A lista chegou com título ou botão em outro idioma**: defina o **Cabeçalho** e o **Texto do botão
  da lista** no nó. Campos vazios usam os textos padrão no idioma configurado na conta.
- **O texto do botão ou do cabeçalho chegou cortado**: o WhatsApp limita esses campos; emojis ocupam
  mais espaço. Encurte o texto ou a variável usada.

## Veja também

- [Visão geral de Automação e Fluxos](/hc/ajuda/articles/automation-flows-overview-pt-br)
- [Regras de automação: gatilhos, condições e ações](/hc/ajuda/articles/automation-flows-regras-de-automacao-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)
- [Bots e Captain (IA de atendimento)](/hc/ajuda/articles/automation-flows-bots-e-captain-pt-br)
- [Roteamento inteligente (Smart Routing)](/hc/ajuda/articles/automation-flows-smart-routing-pt-br)
- [Disparos em massa no Flow Builder](/hc/ajuda/articles/automation-flows-flow-builder-disparos-em-massa-pt-br)