## 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:

| Ação | O que faz |
| --- | --- |
| Listar / filtrar | Veja as sessões por **fluxo**, **conversa** ou **status** (em execução, aguardando, concluída, falha, cancelada), paginadas. |
| Cancelar | Interrompe uma sessão **ativa** (em execução ou aguardando) e libera a conversa. |
| Reexecutar (rerun) | Roda o fluxo **do início** como uma sessão nova (mesmo fluxo, conversa, contato e variáveis). Ideal para uma sessão que falhou ou foi cancelada. |
| Retomar (resume) | Força uma sessão **presa em "aguardando"** a continuar do nó atual, como se a espera tivesse sido satisfeita. |
| Excluir | Remove a sessão e o rastro de passos. Se estava ativa, a conversa é liberada antes. |
| Ações em massa | Selecione várias sessões e **cancelar** (só as ativas) ou **excluir** de uma vez. |

### 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](/hc/ajuda/articles/automation-flows-flow-builder-pt-br)
- [Regras de automação: gatilhos, condições e ações](/hc/ajuda/articles/automation-flows-regras-de-automacao-pt-br)
- [Visão geral de Automação e Fluxos](/hc/ajuda/articles/automation-flows-overview-pt-br)
- [Disparos em massa no Flow Builder](/hc/ajuda/articles/automation-flows-flow-builder-disparos-em-massa-pt-br)