Flow Builder na prática: sessões, versões, relatórios e conexões de banco

Visão geral

Montar o fluxo no canvas é só o começo. Depois vem a operação: colocar o fluxo no ar, manter um histórico de versões para reverter com segurança, acompanhar as sessões (cada execução do fluxo em uma conversa), ler relatórios de desempenho, organizar os fluxos em pastas e conectar dados externos ao nó SQL. A aba Disparos completa a operação: rode um fluxo publicado contra uma audiência inteira (disparo em massa) com cadência anti-bloqueio — veja o artigo dedicado em Veja também.

Este artigo cobre o ciclo de vida de um fluxo na Conversa Labs depois que ele já está desenhado. Para aprender a montar o fluxo em si, veja o artigo do Flow Builder em Veja também.

Pré-requisitos

• O módulo Flow Builder habilitado para a sua conta.
• Administrador para publicar/despublicar, versionar, organizar pastas e gerenciar conexões de banco. Agentes podem listar e acompanhar sessões, abrir relatórios e usar conexões já criadas.
• Para o nó SQL (sql_query): uma conexão de banco externa configurada e testada.
• Para os relatórios e o monitoramento fazerem sentido: pelo menos um fluxo publicado e em uso.

Passo a passo

1. Publique o fluxo quando ele estiver pronto. A partir daí ele passa a ser acionado pelos gatilhos.
2. Acompanhe as sessões na lista de execuções: filtre por fluxo, conversa ou status.
3. Abra os relatórios para ver volume, conclusões e falhas no período.
4. Quando precisar mudar algo, edite o rascunho e publique de novo — a versão anterior fica no histórico para você reverter se necessário.
5. Organize os fluxos em pastas conforme o time ou a finalidade.
6. Se um fluxo consulta dados, crie e teste a conexão de banco antes de usar o nó SQL.

Configurações & opções

Publicação e versões

• Publicar / Despublicar: publicar deixa o fluxo ativo para os gatilhos; despublicar o tira do ar sem apagá-lo.
• Rascunho: a versão de edição. Salvar o rascunho valida a definição e nunca mexe na versão publicada — você edita à vontade sem afetar quem já está rodando.
• Histórico de versões: cada publicação guarda uma versão. Você pode abrir uma versão antiga para conferir o que mudou.
• Restaurar (reverter): traz uma versão anterior de volta como atual.
• Duplicar: cria uma cópia do fluxo para experimentar sem risco para o original.
• Purge (remover definitivamente): apaga o fluxo de forma permanente. Ação irreversível.

Monitoramento de sessões

Uma sessão é uma execução do fluxo dentro de uma conversa. Na lista você pode:

Métricas e alertas do runtime v2

O endpoint protegido /monitoring/metrics publica métricas globais e por tenant para lag de trigger, fila, retomada e vencimento; latência de steps, efeitos e providers; retries, deduplicação, leases expirados, efeitos desconhecidos, DLQ, locks, pools e batches. Ele só existe quando o operador configura OPERATIONS_METRICS_TOKEN. Os alertas são avaliados a cada minuto e os limiares podem ser ajustados por variáveis FLOW_BUILDER_ALERT_*; episódios ficam em um único hash Redis com TTL. Nenhum payload, segredo, contato, conversa ou dado pessoal é publicado. Os índices aditivos de observabilidade devem ser aplicados pelo operador antes de usar essa coleta em grande escala.

Relatórios

Os relatórios mostram as métricas de execução dos fluxos — volume de sessões, conclusões e falhas. Você pode filtrar por fluxo e por período (data inicial e final) para comparar o desempenho ao longo do tempo.

Organização em pastas

Agrupe os fluxos em pastas por time, canal ou finalidade. Apagar uma pasta não apaga os fluxos dentro dela — eles apenas voltam a ficar sem pasta.

Conexões de banco de dados (nó SQL)

O nó SQL consulta um banco externo usando uma conexão que você cadastra uma vez:

• Criar/editar conexão: informe adaptador (PostgreSQL, MySQL ou SQL Server), host, porta, banco, usuário e senha. A senha é somente escrita — é aceita ao salvar, mas nunca é devolvida na tela. Ao editar, deixe a senha em branco para manter a atual.
• Testar conexão: abre o pool e roda um SELECT 1 para confirmar que as credenciais funcionam.
• Testar consulta: roda a query do nó contra uma amostra limitada e mostra as linhas mais o SQL compilado e os parâmetros — você vê exatamente "o que vai rodar", com as {{ variáveis }} resolvidas igual ao runtime.
• Galeria de templates de SQL: trechos prontos somente para leitura (busca, listagem, agregação e junção) já no dialeto do adaptador escolhido, para preencher o campo da consulta sem começar do zero.

O runtime v2 aceita apenas uma instrução de leitura parametrizada por nó. Escritas SQL não aparecem na galeria nem são publicáveis enquanto não houver uma superfície admin com confirmação humana.

Credenciais somente escrita para HTTP e webhook

Quando um administrador provisionar uma credencial do cofre, selecione-a pelo nome no nó — a definição guarda apenas uma referência opaca:

• Requisição HTTP aceita bearer token, API key, Basic Auth ou OAuth2. OAuth2 pode usar access token estático, client_credentials ou refresh_token; a troca de token usa os mesmos limites e proteção contra SSRF da requisição principal.
• Webhook de saída usa uma credencial de assinatura separada.
• Segredos não entram na definição, exportação, histórico ou trace. Rotacionar a credencial mantém a referência do fluxo e invalida o token OAuth2 em cache.

Importar / exportar

• Exportar: baixa a definição de um fluxo para guardar ou levar para outra conta.
• Importar: cria um fluxo a partir de uma definição exportada.
• Testar requisição HTTP: dispara uma requisição isolada (sem rodar o fluxo inteiro) para conferir URL, cabeçalhos e resposta antes de usá-la no nó.

Casos de uso

• Mudar um fluxo no ar com segurança: edite o rascunho, publique e, se algo der errado, restaure a versão anterior em segundos.
• Recuperar execuções com problema: encontre as sessões com falha pelo filtro de status e reexecute em massa.
• Destravar um atendimento parado: uma sessão "aguardando" que nunca recebeu a resposta pode ser retomada manualmente.
• Consultar pedidos no fluxo: configure uma conexão de banco, valide com "Testar consulta" e use o nó SQL para responder ao cliente com dados reais.

Dicas, limites e boas práticas

• Publique mudanças importantes em horários de menor movimento e mantenha o histórico para reverter.
• Reexecutar cria uma sessão nova; pode ser barrado se o fluxo não estiver mais publicado ou se já houver outra sessão ativa para a mesma conversa e fluxo.
• As ações em massa têm um teto de itens por chamada — para volumes grandes, repita em lotes.
• Trate a senha do banco como segredo: ela é somente escrita e nunca aparece de volta na interface.
• Sempre rode Testar conexão e Testar consulta antes de publicar um fluxo que usa o nó SQL.

Solução de problemas

• Sessão travada em "aguardando": use Retomar (resume) para forçar a continuação do nó atual. Só funciona para sessões nesse estado.
• Sessão falhou ou foi cancelada: use Reexecutar (rerun) para rodar o fluxo do início como uma sessão nova. Se for barrado, confirme que o fluxo ainda está publicado e que não há outra sessão ativa para a mesma conversa.
• A conexão de banco falhou no teste: confira adaptador, host, porta, banco, usuário e senha; verifique se o adaptador está disponível no servidor e se a rede permite o acesso.
• Fluxo publicado, mas não dispara: confira o gatilho e se o fluxo está vinculado à caixa de entrada certa; veja se há erro nas sessões recentes e se a versão publicada é a esperada.

Veja também

• Flow Builder: construir fluxos conversacionais visualmente
• Regras de automação: gatilhos, condições e ações
• Visão geral de Automação e Fluxos
• Disparos em massa no Flow Builder