Automações e flows

Use flows para reagir a eventos, receber dados, tomar decisões e executar ações sem intervenção manual. Esta página explica o editor e o catálogo atual. Para segredos, webhooks e segurança de chamadas externas, consulte Credenciais, webhooks e integrações.

Antes de começar

• Cadastre clientes, projetos, equipes e status que serão usados pelo flow.
• Conecte o WhatsApp antes de criar ações de mensagem.
• Crie credenciais em Credenciais de workflow sem colocar tokens diretamente nos nodes.
• Use uma conta com permissão operacional para testar. Publicação, ativação, retenção e exclusão exigem permissão de administração.

Entender o ciclo de vida

Rascunho → validar/preview → testar → publicar versão → ativar → acompanhar execuções

1. Rascunho: é a definição editável. Salvar aumenta a revisão do draft e evita que duas abas sobrescrevam alterações silenciosamente.
2. Validação: verifica nodes, conexões, parâmetros, credenciais e políticas de erro. Erros bloqueiam a publicação; avisos devem ser revisados.
3. Preview: renderiza expressões com um contexto de exemplo do trigger selecionado. Não executa ações reais.
4. Teste: executa um snapshot do draft em modo isolado. HTTP, IA, WhatsApp e alterações operacionais são simulados.
5. Publicação: cria uma versão imutável e substitui os triggers publicados. O draft continua editável.
6. Ativação: somente um flow publicado e marcado como Ativo recebe eventos de produção.
7. Execução: o histórico mostra status, duração, nodes, esperas, tentativas e logs.

Depois de publicar, abra Triggers publicados e confirme cada entrada. Restaurar uma versão antiga copia sua definição para o rascunho; a produção só muda após publicar novamente.

Modelos de flow

Em Modelos de flow, gestores podem instalar modelos públicos ou pertencentes à própria empresa. A instalação valida a definição e cria um novo flow em rascunho, inativo e ainda não publicado. Revise credenciais, equipes, IDs e textos antes de testar; instalar um modelo nunca deve ser tratado como ativação automática.

Montar e validar um flow

1. Acesse Flows e crie um flow com nome descritivo.
2. Mantenha pelo menos um trigger e conecte sua saída ao primeiro node.
3. Selecione cada node e preencha os campos obrigatórios.
4. Em expressões Twig, use o seletor de contexto em vez de digitar caminhos de memória.
5. Defina a política de erro de cada ação:
   • Parar: falha a execução imediatamente.
   • Continuar: registra aviso e segue pela saída principal.
   • Direcionar erro: segue pela saída error; só existe nos nodes que oferecem essa porta.
6. Salve, valide e corrija todos os erros.
7. Abra Testar draft, selecione cada trigger e execute cenários de sucesso e falha.
8. Publique, ative e confira o histórico após o primeiro evento real.

Triggers disponíveis

Triggers não recebem conexão de entrada e entregam o contexto na saída main.

Trigger	Configuração obrigatória	Como inicia	Limitações e falhas comuns
Evento do domínio (domainEventTrigger)	Um evento do catálogo fechado	Uma ação interna da mesma empresa publica o evento	Não aceita nomes livres; o flow precisa estar publicado e ativo.
Webhook (webhookTrigger)	Nada; assinatura HMAC é opcional por credencial apiKey	POST na URL exclusiva publicada, com JSON e Idempotency-Key	Corpo acima do limite é recusado; assinatura inválida retorna 403; chave ausente retorna 422.
Agendamento (scheduleTrigger)	Expressão cron e fuso IANA	Scheduler avalia a expressão a cada minuto	Exige scheduler em execução; cron ou fuso inválido bloqueia publicação.
Manual (manualTrigger)	Nada	Usuário autorizado clica em Executar e pode enviar JSON	Só é executável depois de publicado e ativado.

Eventos do domínio

Evento	Quando é emitido
customer.created	Um cliente é cadastrado.
project.created	Um projeto é criado.
project.recurrence_due	Uma recorrência de projeto vence e é processada.
project_update.published	Uma atualização de projeto é publicada.
project.status_changed	O status de um projeto muda.
issue.reported	Uma ocorrência é registrada.
operational_event.scheduled	Um evento operacional é agendado.
portal.comment.created	Um comentário é enviado pelo portal.
whatsapp.message.received	Uma mensagem chega pelo WhatsApp conectado.

Trigger manual

1. Publique e ative o flow.
2. Abra Triggers publicados.
3. No card do trigger manual, clique em Executar.
4. Informe opcionalmente um objeto JSON e confirme.
5. Abra a execução criada. Se houver mais de um trigger manual, use o card correspondente ao ramo desejado.

Agendamento

Informe uma expressão cron, como 0 9 * * 1-5, e um fuso, como America/Sao_Paulo. O scheduler roda a cada minuto sem sobreposição e usa uma chave idempotente por horário. O card publicado mostra a próxima execução e indica pausa quando o flow está inativo.

Nodes de lógica e dados

Node	Entrada e configuração	Saídas	Comportamento e limitações
If (if)	Uma entrada main; expressão Twig obrigatória	true, false, error	Renderiza a expressão e interpreta o resultado como booleano. Expressão ausente ou inválida segue a política de erro.
Switch (switch)	Uma entrada; lista ordenada de casos com nome e expressão	Uma porta por caso, default, error	Usa o primeiro caso verdadeiro; casos incompletos são ignorados; sem correspondência usa default.
Merge (merge)	Quantidade de entradas e modo all, append, any ou chooseBranch	main, error	all combina contextos; os demais preservam itens. chooseBranch falha se mais de uma entrada estiver ativa.
Definir variável (setVariable)	Nome, valor Twig e opção de sobrescrever	main, error	Grava em variables.<nome>; sem sobrescrita mantém valor existente. Nome vazio falha.
Validar dados da API (validateApiData)	Fonte (payload, event ou contexto) e regras de campo/tipo	true, false, error	Valida presença e tipo; falhas de regra vão para false, não são erro técnico.

Nodes de espera e controle

Node	Entrada e configuração	Saídas	Comportamento e limitações
Atraso (delay)	Segundos inteiros positivos	main, error	Suspende a execução até o horário calculado. Depende de worker e scheduler para retomar.
Aguardar evento (waitForEvent)	Evento do catálogo e chave de correlação Twig	main, error	Retoma apenas quando evento e correlação coincidirem; chave vazia falha.
Aguardar webhook (waitForWebhook)	Token de retomada renderizado	main, error	Armazena somente o hash; o token precisa ter pelo menos 32 caracteres e deve ser guardado pelo sistema chamador.
Executar flow (executeFlow)	Flow filho e, quando necessário, trigger manual	main, error	Aguarda o filho terminar; exige mesma empresa, versão publicada e ativa; bloqueia recursão.

No node Executar flow, um único trigger manual pode ser inferido. Com vários, escolha explicitamente a entrada. Triggers de evento, webhook e agenda não podem iniciar um subflow.

Nodes operacionais e WhatsApp

Node	Entrada e configuração	Saídas	Comportamento e limitações
Enviar WhatsApp (sendWhatsApp)	Destino, mensagem e opção de aguardar resposta	main, error	Exige número ativo em produção. Pode suspender até uma resposta correlacionada. Em teste apenas simula.
Criar ocorrência (createIssue)	Título, descrição, severidade e data	main, error	Requer project.id ou payload.project_id; cria com status aberto. Em teste não grava.
Criar evento operacional (createOperationalEvent)	Título, descrição, local, início e fim opcional	main, error	Requer projeto no contexto; cria com status agendado. Em teste não grava.
Encaminhar conversa para equipe (routeConversationToTeam)	Equipe de escritório e opção de bloquear automação	main, error	Exige conversa WhatsApp no contexto e aceita apenas equipe office; remove atendente atual.
Bloquear automação da conversa (blockConversationWorkflow)	Nenhum parâmetro	main, error	Exige conversa WhatsApp no contexto e impede novos flows até desbloqueio manual.

Nodes de integração

Node	Entrada e configuração	Saídas	Comportamento e limitações
Requisição HTTP (httpRequest)	Método, URL, cabeçalhos, query, corpo e timeout; credencial Bearer/Basic opcional	main, error	Timeout entre 1 e 60 s, sem redirects, resposta limitada e bloqueio de redes privadas. Resposta HTTP de erro segue a política do node.
Requisição de IA (providerAiRequest)	URL base, modelo, mensagens e credencial apiKey obrigatória	main, error	Usa endpoint compatível com /chat/completions, timeout de 60 s, sem redirects e sem acesso a redes privadas. Em teste retorna simulação.

As saídas de HTTP incluem status, indicador de sucesso, cabeçalhos, corpo e JSON. As saídas de IA incluem status, resposta do provedor, conteúdo e uso. Segredos conhecidos são removidos dos dados persistidos, mas evite enviar informações sensíveis desnecessárias.

Testar sem afetar produção

Na tela Testar draft:

1. Selecione o trigger que representa o ramo.
2. Revise o contexto de exemplo e ajuste somente os campos necessários.
3. Execute e acompanhe cada node.
4. Para flows de WhatsApp que aguardam resposta, use o chat de teste para continuar a execução.

O modo de teste não envia HTTP, IA ou WhatsApp reais e não cria ocorrências, eventos ou alterações reais em conversas. Ele serve para validar grafo, Twig, decisões e encadeamento.

Acompanhar, restaurar e reter

• Execuções: filtre e abra uma execução para ver status, entrada permitida, saída, espera, erro e logs.
• Métricas: consulte contagem por status, duração média, tentativas, esperas e falhas de integrações no período.
• Versões: compare a versão publicada com o draft e restaure uma versão para o rascunho quando necessário.
• Retenção: por padrão, execuções de produção ficam 90 dias, manuais/teste 30 dias e logs 30 dias. O payload final fica no modo redacted, preservando a estrutura, não os valores.

Alterar retenção ou excluir uma execução é ação administrativa. Antes de reduzir prazos ou usar payload completo, valide requisitos de suporte, privacidade e auditoria.

Checklist de publicação

• [ ] Todos os triggers foram testados separadamente.
• [ ] Não há erro de validação nem aviso sem análise.
• [ ] URLs e credenciais apontam para o ambiente correto.
• [ ] Os caminhos error necessários estão conectados.
• [ ] O flow foi publicado e marcado como ativo.
• [ ] Os cards de triggers publicados estão corretos.
• [ ] A primeira execução real foi conferida no histórico.

Diagnóstico rápido

Sintoma	Verifique
O evento aconteceu e nada rodou	Flow publicado e ativo, trigger correto e mesma empresa.
Agenda não dispara	Cron, fuso, scheduler e comando workflows:tick.
Execução fica aguardando	Tipo de espera, correlação, callback ou resposta esperada e worker.
Node cai em error	Parâmetros renderizados, contexto de entrada, credencial e política de erro.
Alteração sumiu ao salvar	Outra aba salvou nova revisão; recarregue e reaplique conscientemente.
Produção continua antiga	O draft foi salvo, mas ainda não foi publicado.

Veja também Diagnóstico durante a implantação técnica.