Categorias, pastas e projetos

Conforme sua operação cresce, um único fluxo vira dezenas. Para não se perder, o Atende Direito organiza os fluxos em categorias e pastas, e cria automaticamente um projeto com um fluxo principal sempre que você conecta um canal.

---

Categoria do fluxo: chat ou workflow

Todo fluxo tem uma categoria, que descreve o propósito dele. Você define essa categoria na tela "Novo Fluxo", no seletor de tipo: a opção Chat e a opção Fluxo de Trabalho. A categoria responde a uma pergunta simples: "esse fluxo conversa com o cliente, ou é um processo que roda sob demanda?".

Categoria	Para que serve	Como começa
Chat	Fluxo conversacional principal — é ele que atende o cliente.	Gatilho Mensagem Recebida.
Fluxo de Trabalho	Processo executável sob demanda — uma rotina que você dispara quando precisa (gerar um documento, consultar um sistema, abrir um chamado).	Gatilho Manual — disparado por um atendente, pelo chat ou por outro fluxo.

Dica

Pense no Chat como o atendente que fica na linha com o cliente, e no Fluxo de Trabalho como uma "tarefa" que esse atendente aciona quando precisa resolver algo específico.

Regra importante

Todo Fluxo de Trabalho pode ser chamado por outro fluxo — mas o modo de execução que você escolhe (síncrono ou assíncrono) determina como isso pode acontecer:

Modo de execução	Pode ser chamado por
Síncrono (padrão)	Subfluxo Inline e Subfluxo com Retorno
Assíncrono	Subfluxo Assíncrono

O modo é configurado no editor do fluxo: selecione o nó Start e use o toggle "Modo de execução: Síncrono | Assíncrono". Em modo Assíncrono, a seção "Saídas do subfluxo" não aparece — Fluxos de Trabalho assíncronos só recebem entradas, sem devolver nada (é um disparo do tipo "não espera resposta").

Se você tentar trocar o modo de um Fluxo de Trabalho que já é chamado por outros fluxos de forma incompatível com o novo modo, a alteração é recusada — assim você não quebra, sem querer, um fluxo que depende dele.

Já os fluxos de categoria Fluxo de Trabalho recebem automaticamente o gatilho Manual no nó Start, mesmo que o fluxo não seja marcado como principal.

---

Pastas

Fluxos de qualquer categoria podem ser organizados em pastas. As pastas são compartilhadas: uma mesma pasta pode conter fluxos de Chat e Fluxos de Trabalho ao mesmo tempo.

• Na interface, a lista é filtrada por categoria — ao visualizar os Fluxos de Trabalho, você vê apenas esses em cada pasta; ao visualizar os fluxos de Chat, apenas esses.
• A estrutura de pastas em si não muda: é a mesma organização de sempre, só que agora com o filtro de categoria por cima.

Dica

Use pastas para agrupar por assunto (ex.: "Financeiro", "Jurídico", "Onboarding") e deixe a categoria cuidar da separação entre conversa e processo. Assim um mesmo tema mantém seu fluxo de Chat e seus Fluxos de Trabalho lado a lado.

---

Projeto e fluxo principal automáticos

Quando você conecta um novo canal (WhatsApp Cloud, Direct, QR, webchat ou genérico), o Atende Direito provisiona automaticamente:

1. Um projeto — exatamente um por canal.
2. Um Fluxo Principal dentro desse projeto — categoria Chat, marcado como fluxo principal daquele canal.

Ou seja: assim que o canal existe, você já tem um fluxo de atendimento pronto para editar, sem precisar criar nada manualmente.

Canal criado
  → Projeto provisionado — 1 por canal
    → Fluxo Principal criado (categoria Chat, marcado como principal)
      → Pronto para editar e publicar

Essa provisão nunca duplica nada: se por algum motivo o canal for reprocessado, nenhum projeto ou fluxo repetido é criado.

Dica

Esse comportamento pode ser desligado em ambientes de configuração avançada (por exemplo, para não interferir em testes automatizados). No dia a dia, ele fica sempre ativo.

Escopo de canal em triggers de evento

Quando um evento que carrega informação de canal dispara um fluxo — por exemplo, uma mensagem recebida, que já sabe de qual conversa e canal ela veio —, apenas fluxos cujo projeto pertence ao mesmo canal são disparados. Fluxos de projetos de outros canais do workspace são ignorados automaticamente.

Eventos que não carregam informação de canal (ex.: um novo negócio criado, uma etiqueta adicionada a um contato) continuam disparando qualquer fluxo inscrito do workspace, sem esse filtro.

Esse comportamento evita que uma mensagem recebida em um canal dispare fluxos de atendimento de outro canal, mantendo as linhas de comunicação separadas.

Atenção

Esse filtro aplica-se apenas a eventos que carregam informação de canal. Fluxos de Trabalho disparados manualmente ou por webhook continuam respondendo normalmente, independente de qual canal está associado.

---

Executar um workflow a partir do chat

Durante um atendimento, o chat pode disparar um Fluxo de Trabalho e passar automaticamente o contexto da conversa para ele. É assim que um atendente (ou o próprio fluxo de chat) aciona uma rotina — por exemplo, gerar um contrato ou consultar um processo — sem sair da conversa.

Ao disparar, a plataforma injeta nas variáveis do Fluxo de Trabalho:

Variável	O que contém
conversation.id	Identificador da conversa de onde o Fluxo de Trabalho foi disparado
channel.id	Identificador do canal da conversa
contact.id	Identificador do contato atendido

Assim, o Fluxo de Trabalho já "sabe" com quem está falando e por qual canal, sem configuração extra.

Atenção

Só é possível disparar um Fluxo de Trabalho que tenha uma versão publicada. Se o fluxo ainda não foi publicado, o disparo é recusado.

---

Para desenvolvedores: endpoints

Os endpoints abaixo pertencem ao módulo Flow Builder e exigem autenticação JWT (Authorization: Bearer {token}). Todos respeitam o escopo de workspace do usuário.

Disparar um fluxo com contexto de conversa

POST /flow-builder/flows/{flow}/dispatch

Dispara um fluxo manualmente. Além de contact_id e initial_vars, o corpo aceita conversation_id e channel_id para injetar o contexto da conversa nas variáveis do fluxo.

Corpo da requisição:

Campo	Tipo	Obrigatório	Descrição
contact_id	ulid	Não	Contato associado à execução.
conversation_id	ulid	Não	Conversa de origem. Injeta conversation.id nas variáveis.
channel_id	ulid	Não	Canal de origem. Injeta channel.id nas variáveis.
initial_vars	object	Não	Variáveis iniciais adicionais.

Respostas:

Status	Quando
202	Disparo aceito. Retorna { "event_id": "..." }.
422	O fluxo não tem versão publicada.
403	A conversa (ou canal) informada pertence a outro workspace.

Listar workflows executáveis de um canal

GET /flow-builder/channels/{channel}/workflows

Retorna os fluxos de categoria workflow publicados (com versão ativa) do projeto associado ao canal. É o endpoint usado pelo chat para listar e disparar os workflows disponíveis.

Respostas:

Status	Quando
200	Lista de workflows publicados do projeto do canal.
404	O canal não possui projeto associado.

Ativar ou desativar um fluxo

PATCH /flow-builder/flows/{flow}/toggle-active

Liga ou desliga o fluxo (campo is_active). Exige a permissão flow-builder.edit.

Corpo da requisição:

Campo	Tipo	Obrigatório	Descrição
is_active	boolean	Sim	true para ativar, false para desativar o fluxo.

Respostas:

Status	Quando
200	Fluxo atualizado. Retorna { "data": Flow }.
403	Usuário sem a permissão flow-builder.edit.
422	Corpo da requisição inválido.

Dica

O contrato do engine de execução não muda: as chaves com ponto (conversation.id, channel.id, contact.id) são lidas de initial_vars, em paridade com o disparo por mensagem recebida.

---

Próximos passos

• Chamar Subfluxo e Desvio — como um fluxo chama outro
• Conectar WhatsApp — vincular um canal e as variáveis injetadas
• Testar e Publicar — publicar uma versão do fluxo