Automações

O Editor de Fluxos é uma ferramenta visual de drag-and-drop para criar automações de atendimento.

Como acessar

1. 1Vá em Automações no menu lateral
2. 2Clique em "+ Novo fluxo" ou edite um existente
3. 3O editor de fluxos será aberto em tela cheia

Interface do editor

• Painel esquerdo — Paleta de nós disponíveis (arraste para o canvas)
• Canvas central — Área de construção visual do fluxo
• Painel direito — Configuração do nó selecionado
• Barra superior — Nome do fluxo, botões salvar/voltar, variáveis globais

Construindo um fluxo

1. 1Todo fluxo começa com um nó Trigger (gatilho)
2. 2Arraste nós da paleta para o canvas
3. 3Conecte os nós arrastando das alças de saída para as alças de entrada
4. 4Clique em um nó para configurá-lo no painel direito
5. 5Salve o fluxo com o botão Salvar

Variáveis

Os fluxos suportam variáveis para armazenar e usar dados:

• Variáveis do sistema: contact_name, contact_phone, account_phone
• Variáveis de pergunta: Respostas salvas por nós "Fazer Pergunta" ou "Menu"
• Variáveis globais: Definidas no diálogo de variáveis globais do fluxo
• Variáveis de código: Criadas pelo nó "Código JavaScript"
• Variáveis UTM: utm_source, utm_campaign, utm_medium, etc.

Use variáveis com a sintaxe {{nome_variavel}} em mensagens.

Templates de fluxo

Ao criar um novo fluxo, você pode escolher um template pré-construído:

• Atendimento com menu
• Qualificação de leads
• FAQ automático
• Pesquisa NPS

O nó Trigger define quando o fluxo será iniciado. Tipos disponíveis:

Palavra-chave (keyword)

O fluxo inicia quando o cliente envia uma mensagem contendo a palavra-chave configurada.

• Exemplo: Palavra-chave "cardápio" → cliente envia "Quero ver o cardápio" → fluxo inicia

Primeira mensagem (first_message)

O fluxo inicia automaticamente quando um novo contato envia a primeira mensagem. Ideal para boas-vindas.

Qualquer mensagem (any_message)

O fluxo inicia em qualquer mensagem recebida (quando não há outro fluxo ativo). Use com cuidado.

Webhook (webhook)

O fluxo é disparado via chamada HTTP externa. Útil para integrações com sistemas externos.

Campanha UTM (utm_campaign)

O fluxo inicia quando a conversa tem dados UTM correspondentes. Configure filtros por:

• Campanha (utm_campaign)
• Fonte (utm_source)
• Meio (utm_medium)

Campos vazios = curinga (aceita qualquer valor). Pelo menos um campo deve ser preenchido.

Agendado (schedule)

Disponível em fluxos do tipo Agendada (flow_type = 'scheduled'). O gatilho dispara em horário programado (intervalo regular ou expressão cron). Não é reativo a mensagens — é proativo. Configurado pelo ScheduleConfigDialog ao clicar no nó Trigger de uma automação agendada. Use junto com requestNode + loopNode para buscar dados externos e processar em lote. Veja "Automações agendadas" para detalhes.

Ativando o gatilho

Após criar e salvar o fluxo, vá na lista de automações e clique em "Ativar" para associar o gatilho a uma conta WhatsApp.

Nós de Mensagem

Nós de Lógica

Nós de Ação

Anotações no canvas

O nó Código JavaScript permite executar código personalizado dentro do fluxo em um sandbox seguro.

Variáveis disponíveis

• variables — Objeto read-only com todas as variáveis do fluxo
• output — Objeto para escrever resultados (salvos como variáveis)
• fetch — Função para fazer requisições HTTP
• console.log — Para debug (visível nos logs do servidor)
• JSON, Math, Date, Buffer — Utilitários padrão

Exemplo: Consultar API externa

const resp = await fetch('https://api.exemplo.com/dados', {
  headers: { 'Authorization': 'Bearer token123' }
});
const data = await resp.json();
output.nome_cliente = data.nome;
output.saldo = data.saldo;

Configurações

• Timeout — Tempo máximo de execução (padrão: 5000ms)
• Em caso de erro — continue (segue o fluxo) ou end (encerra)
• saveAs — Salva o objeto output inteiro como JSON em uma variável

Dicas

• Use output.chave = valor para criar variáveis que podem ser usadas nos próximos nós
• O código roda em sandbox isolado (node:vm) — sem acesso ao filesystem
• Ideal para integrações com APIs externas, cálculos e transformações de dados

As Automações Agendadas são fluxos proativos que disparam em intervalos regulares (cron/intervalo), sem depender de uma mensagem recebida. Ideais para consultar APIs externas e notificar contatos em horários definidos.

Diferença entre os tipos

• Por Trigger — reativa: dispara quando uma mensagem chega (keyword, primeira mensagem, webhook, UTM)
• Agendada — proativa: dispara na hora marcada (a cada X minutos/horas/dias, ou cron)

Os dois tipos usam o mesmo editor visual (React Flow) com todos os nós disponíveis.

Como criar uma automação agendada

1. 1Vá em Automações → clique em "+ Nova Automação"
2. 2No diálogo, escolha "Agendada"
3. 3O editor abre já no modo agendado — o nó de trigger vira um nó de Agendamento
4. 4Clique no nó de Agendamento para configurar: intervalo/cron, fuso horário
5. 5Monte o fluxo normalmente (enviar mensagem, webhook, loop, etc.)
6. 6Salve e ative o agendamento

Configuração do agendamento

• Tipo: Intervalo simples (ex: a cada 30 minutos) ou Cron (ex: 0 8 * * 1-5 = seg-sex às 8h)
• Fuso horário: São Paulo, Manaus, Fortaleza, UTC, etc.

Padrão típico de uso

1. 1Agendamento dispara no horário configurado
2. 2requestNode (GET) consulta uma API externa e salva a resposta em {{items}}
3. 3loopNode itera sobre cada item do array
4. 4Dentro do loop — define contato (setContactNode), envia template, etc.
5. 5requestNode (POST) no final atualiza o status na API

Exemplo: Confirmação de consultas diárias

• Cron: 0 9 * * * (todo dia às 9h)
• GET https://clinica.com/api/consultas-hoje → salva em consultas
• Loop em consultas → por item, envia template de confirmação
• Depois do loop, POST https://clinica.com/api/confirmadas com os IDs

Listagem

Vá em Automações → aba "Agendadas" para ver todas suas automações agendadas, execuções recentes, próxima execução e toggle de ativo/inativo.

O nó Loop / Para Cada itera sobre um array e executa um ramo do fluxo para cada item. Essencial para processar listas retornadas por APIs.

Duas saídas visuais

• ↻ POR ITEM (amber, esquerda) — conecte aqui os nós que devem rodar em cada iteração
• → APÓS TERMINAR (verde, direita) — conecte aqui o que acontece depois de todas as iterações

Configuração

• Variável do array — nome da variável com o array (ex: resposta salva por um requestNode)
• Nome da variável do item — como acessar o item atual (padrão: item)
• Variável do índice (opcional) — expõe o índice 0-based
• Máximo de iterações — limite de segurança (padrão 100, máx 1000)

Acessando dados no body

Dentro do loop, use:

• {{item}} — item inteiro serializado JSON
• {{item_campo}} — campo específico do objeto (ex: {{item_phone}}, {{item_nome}})
• {{i}} — índice atual (se configurado)

Nós suportados no body

✅ Suportados: sendMessage, sendTemplate, webhook, code, condition, assign (agente/time/tag/status/prioridade), email, CRM, CAPI, delay (limitado a 2s)

❌ Não suportados: askQuestion, menu, buttonReply, aiAgent, sendNps, whatsappFlow (nós que pausam o fluxo). São pulados com um warning no log.

❌ Loops aninhados não são suportados.

Exemplo

1. 1requestNode chama GET /api/pedidos e salva em {{pedidos}} (array)
2. 2loopNode com Array: pedidos, Item: pedido
3. 3No body: sendMessage com texto "Olá {{pedido_cliente}}, seu pedido #{{pedido_id}} foi enviado!"
4. 4Depois do loop: sendMessage final "Enviamos {{pedidos_count}} notificações"

O nó Data e Hora gera, soma, subtrai ou formata datas e salva o resultado em uma variável. Inspirado no nó de Data do n8n.

Operações

Unidades (para add/subtract)

Anos, Meses, Semanas, Dias, Horas, Minutos, Segundos

Formatos de saída

Fuso horário

Padrão: America/Sao_Paulo. Suporta também Manaus, Fortaleza, Belém, Porto Velho, Rio Branco e UTC.

Variável de origem (opcional)

Para operações de add/subtract/format, pode informar uma variável contendo a data base. Aceita:

• ISO 8601 (ex: 2026-04-11T21:30:00Z)
• Unix timestamp em segundos ou milissegundos

Se vazio, usa a hora atual.

Salvar em

Nome da variável onde o resultado será salvo. Use depois como {{nome_variavel}} em mensagens, webhooks, etc.

Exemplos de uso

1. Calcular "amanhã às 9h":

• Operação: Adicionar
• Quantidade: 1, Unidade: Dia(s)
• Formato: BR data+hora
• Salvar em: amanha

→ Mensagem: "Sua consulta é em {{amanha}}"

2. Data de vencimento (7 dias no futuro):

• Operação: Adicionar
• Quantidade: 7, Unidade: Dia(s)
• Formato: BR data
• Salvar em: vencimento

3. Timestamp atual em ISO para salvar no banco:

• Operação: Data/hora atual
• Formato: ISO 8601
• Salvar em: created_at

O nó Anotação (noteNode) é um post-it visual no canvas do editor. Ele não é executado pelo engine de fluxos — serve apenas para documentar o fluxo para você e sua equipe.

Quando usar

• Explicar a intenção de um bloco complexo
• Marcar uma seção "em construção" ou "depende de X"
• Deixar instruções para outros administradores

Configuração

Comportamento no engine

• Ignorado completamente. Não consome execução, não conta em métricas, não aparece em logs de fluxo.
• Não conectar a outros nós — não há entrada ou saída funcional.

Dicas

• Use cores diferentes para categorizar (amarelo = TODO, vermelho/rosa = warning, verde = OK).
• Coloque uma nota no início do fluxo descrevendo o objetivo geral.
• Em fluxos longos, use notas para separar "seções" lógicas (boas-vindas / qualificação / fechamento).

O nó Pré-Sessão de Resposta (prepareReplySessionNode) cria uma sessão "standby" em outro fluxo, antes do contato responder. Quando o contato eventualmente mandar uma mensagem, o engine entrega essa mensagem para a sessão standby já posicionada no fluxo destino — sem precisar disparar o fluxo do zero.

Útil em padrões como: você acabou de enviar uma mensagem ativa (campanha, broadcast, notificação) e quer que a próxima resposta do contato continue um fluxo específico, em vez de cair na automação reativa padrão.

Configuração

Quando NÃO usar

• Se o objetivo é simplesmente encadear fluxos no momento do disparo, use startFlowNode.
• Se o contato já está em uma sessão ativa, o engine respeita a sessão atual — o standby fica em fila.

Exemplo de cenário

1. 1Campanha em massa envia "Olá! Quer falar com um especialista?"
2. 2Para cada destinatário, prepareReplySessionNode aponta para o fluxo atendimento-vendas no nó askQuestion
3. 3Quando o contato responde "Sim", o engine entrega a resposta direto para a sessão standby — o fluxo de vendas continua sem reset.

O Modo Teste permite executar um fluxo inteiro visualmente, sem tocar na produção. Inspirado no n8n, é a forma segura de validar alterações antes de publicar.

Como acessar

1. 1Abra um fluxo no editor de automações
2. 2Clique no botão "Executar Teste" (amber, ao lado do Salvar)
3. 3O painel de teste abre no lado direito

O que acontece em modo teste

O painel de teste tem 5 abas

1. 1Entrada: telefone simulado, mensagem de gatilho, variáveis iniciais
2. 2Execução: log em tempo real de cada nó executado (clique no tipo do nó → canvas centraliza)
3. 3Mensagens: preview tipo chat das mensagens que seriam enviadas
4. 4Vars: snapshot das variáveis da sessão
5. 5⏸ Resposta: aparece quando o teste pausa — simule texto ou clique no botão/opção

Status visual nos nós (durante teste)

• 🔵 Azul pulsante: nó em execução
• ✅ Verde: concluído com sucesso
• ❌ Vermelho: erro
• ⏸ Amber pulsante: pausado aguardando resposta
• Edges verdes: caminho percorrido até aqui

Mock de Teste (pinned data)

Cada nó importante tem uma seção 🧪 Mock de Teste colapsível na config:

• Requisição HTTP: fixe um JSON de resposta — evita bater em APIs reais
• Fazer Pergunta / Menu / Botões: fixe a resposta simulada — pula a pausa, fluxo roda inteiro
• Agente IA: fixe o que o LLM responderia — economiza tokens

Quando o mock está ativo, o badge "Ativo" aparece e o nó usa o valor em vez de executar.

Testar sem salvar

Por padrão o teste usa o editor atual (incluindo alterações ainda não salvas). Use o toggle em "Entrada" para alternar entre editor atual e versão salva. Ideal: editar → testar → salvar depois que estiver funcionando.

Dica: testar fluxo longo rapidamente

Ative mocks em todos os nós de pausa (askQuestion, menu) com respostas pré-definidas. O teste roda do início ao fim sem intervenção — útil pra regressão.

Limites de segurança

• Máx 10 testes simultâneos por tenant
• Sessão de teste expira em 30min
• Snapshot (editor atual não salvo) limitado a 500 KB