Produto

Fluxos conversacionais

Cobertura completa do builder visual: tipos de nó, variáveis e contexto, transições, integração com Conhecimento e Guardrails, cascata de Fila no handoff e sessões de teste.

Atualizado em 03 de maio de 2026

O que é um Fluxo Conversacional

O Fluxo Conversacional é o subtipo de Fluxo desenhado em editor visual (canvas com nós e arestas) e executado por um motor de IA generativa baseado em modelos da OpenAI. É a opção mais flexível do catálogo de Fluxos — cobre de URAs com IA até atendimentos omnichannel completos com integração a sistemas externos.

A regra de copy continua: a UI sempre diz “Fluxo”, nunca “Bot” ou “Agente IA”. O nó que conversa com o contato chama-se Conversa, não “nó do bot”.

O builder

O canvas usa ReactFlow com paleta lateral arrastável, painel de propriedades à direita e barra de zoom no rodapé. As ações principais:

Arrastar tipo de nó da paleta para o canvas para criar.
Ligar saídas a entradas desenhando uma aresta entre os pontos de conexão (handles).
Selecionar um nó abre o painel direito com as propriedades dele.
Configurações globais do Fluxo (modelo LLM padrão, prompt do sistema, anexos de Conhecimento e Guardrails) ficam no botão de configurações no topo.

Tipos de nó

A paleta tem 16 tipos. Os mais usados no dia a dia:

Início e fim

Início — toda execução começa aqui. Sempre presente, único, não-removível.
Encerramento — termina a Conversa. Pode ter mensagem final.

Conversa com o contato

Conversa — o nó que de fato fala com o contato via LLM. Tem prompt próprio, modelo configurável (padrão herdado do Fluxo) e regras de transição para escolher o próximo nó. Suporta limite de tentativas e destino de fallback quando o contato não converge para uma transição válida.
Mensagem — envia uma mensagem fixa, sem LLM. Útil para confirmações curtas ou texto que não pode variar.
Capturar Entrada — pede um valor específico ao contato (texto, número, data) e armazena em variável.
Aguardar Resposta — aguarda mensagem do contato com timeout configurável; saída por “respondeu” ou “expirou”.
SMS — envia um SMS pelo provedor configurado (independente do canal da Conversa).

Decisão e fluxo de controle

Decisão — bifurca o Fluxo conforme uma condição. Modo value é o estável; os modos expression e ai aparecem na UI mas estão declarados como inertes em runtime.
Divisão Lógica — split paralelo simples por valor de variável.
Digitar Tecla — captura DTMF em chamadas de voz (URA híbrida).

Variáveis e cálculo

Extrair Variável — extrai um valor estruturado da última fala do contato usando IA, salva em variável.
Função — executa lógica determinística sobre variáveis (transformação de texto, formatação, cálculo).

Integração com sistemas externos

Chamada API — faz uma requisição HTTP para um sistema externo, injeta o retorno em variável. Cabeçalhos e corpo aceitam interpolação de variáveis. O campo retry_count aparece na UI mas o runtime ainda não aplica retry — trate como 1 tentativa única até ratificação.
MCP — invoca uma ferramenta exposta via Model Context Protocol.
Notificar Time — dispara notificação para um time externo (e-mail, webhook). Suporta modo fire-and-forget — o Fluxo segue sem esperar a entrega.

Transferência

Transferir para Atendente — handoff para humano em uma Fila configurada (detalhes em Cascata de Fila).
Transferir Chamada — transfere uma chamada de voz para um número externo (ramal, parceiro, especialista).

Variáveis e contexto

O Fluxo mantém um contexto de variáveis acessível por todos os nós. As variáveis vêm de três lugares:

Pré-carregadas — dados do contato (nome, telefone, e-mail) e da Campanha (mailing, tags) chegam preenchidos quando a Conversa começa.
Capturadas — nós como “Capturar Entrada” e “Extrair Variável” gravam novos valores no contexto à medida que a conversa avança.
De API — o nó “Chamada API” armazena o retorno em variável.

Para usar uma variável dentro de um prompt, mensagem, header ou body, escreva {{nome_variavel}}. O builder destaca variáveis válidas e sinaliza referências a variáveis inexistentes.

Modos LLM vs determinístico

Cada Fluxo Conversacional combina:

Nós com LLM (Conversa, Extrair Variável, Decisão modo ai — quando ratificado) — interpretação aberta, custo por tokens, latência maior, comportamento adaptativo.
Nós determinísticos (Mensagem, Capturar Entrada, Função, Decisão modo value, Aguardar Resposta, transferências) — sem LLM, latência baixa, comportamento previsível.

A boa prática é misturar: use Conversa onde a IA agrega valor (triagem, respostas livres), e nós determinísticos onde o caminho é fixo (confirmações, transferências, integrações). Isso reduz custo, latência e superfície de erro de IA.

Conhecimento e Guardrails

O builder permite anexar dois tipos de “trilho” ao Fluxo:

Conhecimento. Bases RAG do tenant que o motor consulta quando o nó Conversa precisa responder com informação proprietária. Indexação assíncrona — bases novas levam alguns minutos para ficarem disponíveis. Detalhes em Base de Conhecimento.
Guardrails. Validações aplicadas em entrada e saída do Fluxo (filtros de conteúdo, bloqueio de PII, restrição de tópicos). Disparos são logados para auditoria. Detalhes em Guardrails.

Ambos são configurados em Configurações globais do Fluxo, não por nó. Vale para toda a Conversa que esse Fluxo executar.

Cascata de Fila no handoff

Quando um nó Transferir para Atendente dispara, a Fila de destino é resolvida em três níveis, do mais específico para o mais genérico:

Fila configurada no nó. Se o nó tem Fila explícita, usa essa.
campanha.fila_id. Se o nó não tem, usa a Fila padrão da Campanha que está executando.
channel_route.default_queue_id. Se a Campanha também não tem, usa a Fila padrão da Rota do Canal.
Fallback. Se nada resolver, o handoff falha de forma explícita — o motor não inventa Fila para evitar entregar Conversa a destino errado.

O nó também tem três modos de transferência:

Modo	Comportamento
queue (padrão)	Distribuição normal pela Fila resolvida.
preferred_agent	Tenta um Atendente específico; se indisponível, cai para a Fila.
direct_agent	Só aquele Atendente. Sem fallback — se offline, segue a `offline_strategy` do nó.

A offline_strategy decide o que acontece quando o Atendente preferencial está offline: cair para a Fila ou usar uma porta de saída separada (“unavailable_port”) que permite o Fluxo seguir um caminho alternativo no canvas.

Limite de tentativas e fallback no nó Conversa

O nó Conversa expõe dois controles para o caso de o contato não convergir para nenhuma transição válida (responder fora do escopo repetidamente):

Limite de tentativas. Quantas vezes a IA tenta reconduzir antes de desistir.
Destino de fallback. Para qual nó o Fluxo segue quando o limite é atingido — tipicamente um nó de Encerramento com mensagem de “vou te transferir para um Atendente” ou um Transferir para Atendente direto.

Isso evita loops infinitos quando o contato escreve algo que a IA não sabe encaminhar.

Sessões de teste

Antes de publicar, teste o Fluxo no painel de teste integrado ao builder ou em Conversas → Sessões de Teste:

Inicia uma Conversa de teste contra a versão atual do Fluxo (rascunho ou publicado).
Permite simular respostas do contato, ver as transições escolhidas, o conteúdo enviado para o LLM e o retorno.
O log mostra cada nó executado, variáveis capturadas, custos por nó e disparos de Guardrail.

Publicação e versionamento

Editar um rascunho não afeta as Campanhas em produção.
A publicação cria uma nova versão; Campanhas que apontam para o Fluxo passam a usar a versão publicada na próxima Conversa nova.
Conversas em andamento continuam na versão em que começaram.
Soft delete preserva o histórico — Fluxos excluídos somem da UI mas as Conversas antigas continuam rastreáveis.

Erros comuns

Loop infinito por falta de fallback. Sem limite de tentativas e destino de fallback no nó Conversa, contatos confusos podem girar indefinidamente.
Cascata de Fila quebrada. Se nem o nó, nem a Campanha, nem a Rota têm Fila configurada, o handoff falha. Configure ao menos um nível.
Confiar em retry implícito do nó Chamada API. Não acontece hoje — trate cada chamada como única e desenhe um caminho explícito para erro (ex.: variável api_status + nó Decisão).
Misturar variáveis com {{ }} mal formados. O builder destaca variáveis válidas; revise antes de publicar.
Anexar Conhecimento e esperar resposta imediata. A indexação assíncrona leva alguns minutos; cheque o status no menu Conhecimento antes de testar.