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.

---

Categoria e automação pausada

Quando a automação de uma conversa está pausada (veja Controle da IA no chat), nem todo fluxo fica bloqueado. A categoria do fluxo decide isso:

• Fluxos de categoria Chat respeitam a pausa — se a automação está pausada naquela conversa, o fluxo não dispara, porque é ele quem conversa com o cliente e a IA não deve responder enquanto um humano estiver no controle.
• Fluxos de categoria Fluxo de Trabalho ignoram a pausa — eles continuam disparando normalmente mesmo com a conversa pausada. A lógica é que um Fluxo de Trabalho é um processo (gerar um documento, consultar um sistema), não uma resposta ao cliente, então não faz sentido travá-lo só porque um atendente assumiu a conversa.

A regra completa, avaliada fluxo a fluxo: o disparo acontece se qualquer uma das condições abaixo for verdadeira.

1. O evento é de ciclo de vida da conversa (ex.: conversa encerrada) — esses disparam pausada ou não, com uma exceção: quando a conversa é encerrada logo após ser transferida ou assumida por um humano, o gatilho Conversa encerrada não dispara fluxos Chat (evita o bot reagir a um atendimento que o humano acabou de fechar). Fluxos de Fluxo de Trabalho disparam normalmente nesse caso — use essa categoria para mensagens de "atendimento finalizado", CSAT ou tags de encerramento.
2. A automação não está pausada naquela conversa.
3. O fluxo é de categoria Fluxo de Trabalho.

Categoria do fluxo	Automação pausada?	Dispara?
Chat	Não	Sim
Chat	Sim	Não
Fluxo de Trabalho	Não	Sim
Fluxo de Trabalho	Sim	Sim

Atenção

Esse gate de pausa só se aplica ao caminho de evento — ou seja, quando um evento do sistema (mensagem recebida, etiqueta adicionada, negócio criado etc.) é quem dispara o fluxo. Gatilhos Entrada do usuário (resposta ou timeout de um nó em espera), Manual, Webhook, Trigger Agenda, Envio de Formulário, Data do Contato e Campo do Contato Alterado não passam por esse gate: eles disparam (ou destravam uma execução em espera) independentemente de a conversa estar pausada, para qualquer categoria de fluxo. Isso é intencional — esses gatilhos representam uma ação explícita (um atendente, um sistema externo, um horário programado ou um dado do próprio contato), não uma reação automática a uma mensagem do cliente.

---

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.

Isolamento por workspace e projeto

Projetos e pastas pertencem a um único workspace e nunca são compartilhados entre workspaces. Dentro do workspace, as pastas também respeitam o projeto:

• Uma pasta pai precisa pertencer ao mesmo projeto da pasta que está sendo criada ou movida.
• A pasta de um fluxo (folder_id) precisa pertencer ao mesmo projeto do fluxo.
• Referências a projeto ou pasta de outro workspace ou de outro projeto são recusadas antes de qualquer alteração de dados — nada é criado, movido ou salvo parcialmente.
• Mover para a raiz continua permitido: enviar o pai ou a pasta com valor vazio ou nulo tira o item de qualquer pasta.

---

Lista de fluxos: buscar, filtrar e renomear

A tela Flow Builder (/flow-builder) lista os fluxos por projeto e por pasta. Cada card de pasta mostra quantos fluxos ela tem, somando as subpastas.

Carregamento e contador

Os fluxos carregam de 30 em 30 conforme você rola a lista (scroll infinito). Se preferir, use o botão Carregar mais. O contador mostra "X de Y": quantos já foram carregados e o total que atende aos filtros atuais.

Renomear um fluxo

No menu (três pontinhos) do card do fluxo, escolha Renomear. No diálogo Renomear fluxo:

• O nome é obrigatório e aceita até 160 caracteres.
• O botão Salvar fica desabilitado se o nome estiver vazio ou igual ao atual.

Busca

O campo Buscar em todo o projeto... procura por nome, slug ou descrição, sem diferenciar maiúsculas de minúsculas.

• Durante a busca, o resultado cobre o projeto inteiro (todas as pastas) e a seção de subpastas fica oculta. O título da seção vira Resultados em todo o projeto.
• Sem texto de busca, a lista volta a ficar restrita à pasta aberta.

Filtros de status

Os chips acima da lista filtram por situação:

Chip	O que mostra
Todos	Todos os fluxos.
Publicados	Fluxos que já têm versão publicada.
Rascunhos	Fluxos nunca publicados.
Ativos	Fluxos com o interruptor de ativo ligado.
Inativos	Fluxos com o interruptor de ativo desligado.

Filtros avançados

O botão Filtros abre o painel de filtros avançados e mostra um contador quando há filtros aplicados.

Filtro	Opções
Tipo	Chat ou Fluxo de trabalho.
Papel	Só o principal ou só subfluxos.
Atualizado entre	Duas datas (início e fim).
Ordenar por	Principal primeiro A-Z (padrão), Nome, Última atualização ou Data de criação. Um botão alterna entre ordem crescente e decrescente.

Use Limpar tudo para remover todos os filtros de uma vez.

Filtros personalizados

Dentro do painel de filtros, use Salvar estes filtros como... para guardar a combinação atual com um nome. Os filtros salvos aparecem como chips em Meus filtros, acima da lista: um clique aplica a combinação e o X remove o filtro salvo.

Atenção

Os filtros personalizados ficam salvos no seu navegador e não são compartilhados com a equipe. Em outro navegador ou computador, eles não aparecem.

---

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.

---

Disparar fluxos a partir do chat

O menu da conversa (chat) tem duas ações para disparar um fluxo manualmente. Ambas exigem a permissão flow-builder.edit.

Ação	Categoria disparada	O que faz
Executar workflow	Fluxo de Trabalho	Roda um processo sob demanda (gerar um documento, consultar um sistema) sem sair da conversa.
Disparar automação da conversa	Chat	Faz o robô voltar a responder o cliente naquele atendimento, reproduzindo o contexto da última mensagem recebida.

As duas ações abrem a mesma janela de escolha, igual à do Executar automação: um campo de busca por nome ou descrição (a busca considera todos os fluxos do canal, não só os já exibidos), lista em ordem alfabética que carrega mais itens ao rolar, setas para navegar e Enter para disparar o fluxo selecionado.

Executar workflow

Dispara um fluxo de categoria Fluxo de Trabalho e passa 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:

Variável	O que contém
conversation.id	Identificador da conversa de onde o fluxo 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 que tenha uma versão publicada. Se o fluxo ainda não foi publicado, o disparo é recusado.

Disparar automação da conversa

Dispara um fluxo de categoria Chat para a conversa aberta, fazendo o robô voltar a responder o cliente naquele atendimento.

Essa ação existe para resolver um problema específico: um fluxo conversacional só dispara sozinho quando chega uma mensagem do contato (o gatilho Mensagem Recebida). Se o fluxo foi publicado depois que a mensagem já tinha chegado, aquele atendimento fica órfão — o gatilho não existia no momento em que a mensagem entrou, então nada roda automaticamente. Antes desta ação, corrigir isso exigia intervenção manual direto em produção; agora existe um caminho suportado pela própria interface.

Ao disparar, a plataforma reproduz o contexto do último inbound do contato naquela conversa (a mensagem mais recente enviada pelo cliente), como se o fluxo tivesse rodado no momento em que ela chegou. Isso popula os escopos event.* e contact.* do fluxo exatamente como um disparo real por mensagem recebida — sem esse contexto, um fluxo que testa algo como event.message.sender_type cairia direto no fim sem fazer nada.

Atenção

O disparo manual é uma ação explícita do atendente, não uma reação automática a uma mensagem do cliente — por isso o endpoint de disparo (POST /flow-builder/flows/{flow}/dispatch) aceita mesmo com a conversa pausada, sem exigir Devolver para a IA antes (veja Categoria e automação pausada acima). Veja Automação pausada e disparo de fluxos.

---

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.

Projetos e pastas (isolamento):

Status	Quando
404	O projeto informado não existe ou pertence a outro workspace.
422	Referência de pasta cruzada: parent_folder_id ou folder_id aponta para uma pasta de outro projeto ou workspace. O erro vem no formato padrão { "errors": { campo: [...] } }, sem expor dados do recurso referenciado.

null ou valor vazio em parent_folder_id/folder_id move o item para a raiz e é sempre aceito.

Listar fluxos de um projeto

GET /flow-builder/flows?project_id={projeto}

Resposta paginada (data + meta.current_page, meta.last_page, meta.total). Parâmetros opcionais:

Parâmetro	Valores
search	Texto procurado em nome, slug e descrição (sem diferenciar maiúsculas).
folder_id	ULID da pasta, ou root para só os fluxos sem pasta. Omitido = todas as pastas.
status	live (publicado), draft (nunca publicado), active, inactive.
category	chat ou workflow.
is_main	1 (só o principal) ou 0 (só subfluxos).
updated_from, updated_to	Datas (AAAA-MM-DD), inclusivas.
sort, direction	name, updated_at ou created_at; asc ou desc. Sem sort: principal primeiro, depois A-Z.
per_page	1 a 100 (padrão 50).

Valor inválido retorna 422. A árvore de pastas (GET /flow-builder/folders/tree/{projectId}) traz flows_count em cada pasta, somando as subpastas.

Disparar um fluxo com contexto de conversa

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

Dispara um fluxo manualmente. Exige a permissão flow-builder.edit.

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. O disparo manual ignora a pausa de automação da conversa, para qualquer categoria de fluxo.
channel_id	ulid	Não	Canal de origem. Injeta channel.id nas variáveis.
initial_vars	object	Não	Variáveis iniciais adicionais.
message_id	ulid	Não	Mensagem inbound usada como âncora do replay de contexto (ver nota abaixo). Precisa pertencer à conversa de conversation_id.

Respostas:

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

Dica

Quando conversation_id é informado, o disparo carrega o contexto completo do evento de mensagem recebida, populando os escopos event.* e contact.* do fluxo — o mesmo formato publicado por um inbound real. message_id é opcional: se omitido, a plataforma usa automaticamente a última mensagem inbound do contato naquela conversa como âncora. Sem esse contexto, um fluxo que testa event.message.sender_type, por exemplo, cai direto no fim sem fazer nada — foi exatamente esse o bug corrigido por essa entrega.

Atenção

O disparo manual (POST /flow-builder/flows/{flow}/dispatch) ignora a pausa de automação da conversa, para qualquer categoria de fluxo — é uma ação explícita do atendente, não uma reação automática a uma mensagem do cliente. O gate de automação pausada existe só no caminho de evento (ver Categoria e automação pausada), não neste endpoint.

Listar flows disparáveis manualmente de um canal

GET /flow-builder/channels/{channel}/workflows?category=workflow|chat|all&conversation_id=<ulid>&search=<texto>&per_page=<n>&page=<n>

Lista os flows que podem ser disparados manualmente para o projeto associado ao canal — é o endpoint que alimenta as ações Executar workflow e Disparar automação da conversa no chat.

Parâmetros de query:

Parâmetro	Tipo	Obrigatório	Descrição
category	workflow | chat | all	Não	Filtra por categoria do fluxo. Default workflow, para preservar o comportamento histórico. all remove o filtro.
conversation_id	ulid	Não	Conversa de referência. Quando informado, a resposta ganha meta.automation_paused com o estado de pausa daquela conversa.
search	string (até 160)	Não	Texto procurado em nome, slug e descrição, sem diferenciar maiúsculas.
per_page	integer (1 a 100)	Não	Liga a paginação. Sem ele, a resposta traz a lista completa, sem paginar, como antes.
page	integer	Não	Página desejada, quando per_page é informado.

Só entram na lista fluxos ativos (is_active = true) e com versão publicada (active_version_id preenchido), em ordem alfabética.

Respostas:

Status	Quando
200	Lista de flows. Com per_page, o meta traz a paginação (current_page, last_page, total). Com conversation_id, o meta inclui também automation_paused, reason e until.
403	conversation_id informado pertence a outro workspace.
404	O canal não possui projeto associado.

Dica

meta.automation_paused existe para a UI avisar antes do clique que o disparo de um flow de Chat vai cair no 409 — sem precisar de uma segunda chamada só para checar o estado de pausa da conversa.

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

As variáveis conversation.id, channel.id e contact.id ficam disponíveis no fluxo da mesma forma que no 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
• Controle da IA no chat — como a automação pausa e retoma numa conversa