Gatilho Manual

O nó Manual (manual_trigger) inicia um workflow sob demanda — pelo painel de teste do editor, pelo botão play no nó ou por uma chamada explícita à API de execução manual. É essencial para desenvolvimento, QA e execuções iniciadas por operadores que não devem aguardar um webhook ou agendamento.

Abra Automações → paleta Triggers → Manual.

Figura 1: Gatilho Manual — botão play e gaveta de execução de teste

O que ele faz

Execuções manuais usam o mesmo caminho do engine que gatilhos de produção, mas são marcadas com trigger_source: manual para que você possa filtrá-las no Execution history.

Configuração — passo a passo

1. Adicionar o nó Manual

1. Abra ou crie um workflow.
2. Arraste Manual de Triggers para o canvas.
3. Conecte-o ao seu fluxo (em paralelo ao Webhook ou Schedule se usar design com múltiplos gatilhos).

Você pode ter Webhook + Manual ou Schedule + Manual em um workflow — padrão comum: tráfego de produção via Webhook/Schedule, validação via Manual.

2. Executar pelo botão play do nó

1. Clique no ícone de play no cabeçalho do nó Manual.
2. A gaveta Test workflow abre (lado direito).
3. Opcionalmente edite o payload JSON para simular dados de webhook.
4. Clique em Run — a execução inicia imediatamente com trigger_source: manual.

3. Executar pela gaveta de teste

1. Abra a barra de ferramentas do editor → Test (ou gaveta de teste).
2. Se existir um nó Webhook, a gaveta também mostra a URL do webhook — execuções manuais ignoram a URL e usam seu payload diretamente.
3. Cole um JSON de exemplo correspondente ao que um webhook real enviaria:

{
  "phone": "5511999999999",
  "name": "Test User",
  "order_id": "TEST-001"
}

1. Execute e observe os nós acenderem em tempo real no canvas.

4. Inspecionar resultados

1. Expanda cada nó na gaveta de teste para ver o JSON de entrada/saída.
2. Abra Execution history para um registro persistente.
3. Corrija nós com falha, salve e execute manualmente de novo até o fluxo estar limpo.

5. Salvar e manter Manual para operações

Deixe o nó Manual em workflows de produção se operadores precisarem de execuções ocasionais sob demanda (ex.: "reenviar relatório agora"). Remova-o apenas se quiser restringir execuções a fontes automatizadas.

Payload e variáveis

Execuções manuais passam seu JSON de teste para context.trigger — a mesma estrutura que o body do webhook quando você faz POST com JSON:

Dica: espelhe exatamente o JSON de webhook de produção no payload de teste para que os caminhos {{trigger.body.x}} correspondam ao tráfego real.

Exemplo de alinhamento:

{
  "body": {
    "phone": "5511999999999",
    "name": "Maria"
  },
  "query": {},
  "method": "POST",
  "headers": {}
}

Ou JSON plano se seus nós referenciam {{trigger.phone}} diretamente (o engine armazena o payload na raiz de trigger).

Workflows com múltiplos gatilhos

Salvar um workflow com nó Manual define triggers_enabled.manual: true.

O engine seleciona manual_trigger quando trigger_source é manual.

Manual vs teste com Webhook

Execute ambos antes do go-live: Manual para velocidade, Webhook para fidelidade.

Dicas e boas práticas

• Mantenha payloads de exemplo em um nó Text ou Annotation (ou documentação da equipe) para testes repetíveis.
• Nomeie o nó Manual de forma clara (ex.: "Manual — QA only") para que operadores saibam que é intencional.
• Não dependa de Manual para caminhos de produção sensíveis ao tempo — use Webhook ou Schedule.
• Filtre o histórico por origem do gatilho para separar testes manuais do volume real de webhooks.
• Clone o workflow antes de experimentos destrutivos — execuções manuais ainda afetam contatos reais se nós Send apontarem para números de produção.
• Use números de telefone de teste no payload durante o desenvolvimento.
• Combine com Condition — ramo opcional que só envia mensagens reais quando {{trigger.body.live}} é true; omita em testes manuais.

Exemplos de casos de uso

Validar template de mensagem antes da campanha

1. Gatilho Manual com { "phone": "5511888888888", "name": "QA" }.
2. Nó Send message com o texto final.
3. Confirme a formatação em um dispositivo real, depois ative Webhook/Schedule para a fonte em massa.

Operador "executar sincronização agora"

1. Workflow de produção: Schedule noturno + Manual para sob demanda.
2. Operador abre o editor → play no Manual → sincronização com ERP roda imediatamente sem esperar as 02:00.

Depurar fluxo de webhook com falha

1. Copie o payload da execução com falha no histórico de webhooks.
2. Cole na gaveta de teste Manual.
3. Percorra os nós com breakpoints (inspecione I/O de cada nó) para encontrar o erro.

Treinar novos membros da equipe

1. Cópia somente Manual de um workflow de produção.
2. Novos integrantes executam cenários com segurança sem tocar em URLs de webhook externas.

FAQ

Manual funciona em workflows inativos?
Testes no editor geralmente rodam em contexto de teste/dev; confirme no seu plano. O comportamento da API manual de produção exige workflow ativado — verifique mensagens de erro de execução se bloqueado.

Manual é visível para clientes finais?
Não. Apenas usuários com acesso ao editor de workflows podem dispará-lo.

Manual consome os mesmos tokens/limites que produção?
Sim — nós de IA, mensagens e integrações cobram/executam igual às execuções automatizadas.

Posso remover o nó Manual após o lançamento?
Sim. Salvar sem manual_trigger define triggers_enabled.manual: false.

Por que minha execução Manual difere do webhook?
Forma do payload ou ausência de headers / query. Alinhe o JSON de teste com a estrutura real do webhook.

Vários nós Manual?
O engine escolhe o primeiro manual_trigger na definição quando trigger_source é manual — use um nó de entrada Manual por workflow.

Gatilho manual de CRM a partir do board?
Regras de board CRM podem iniciar workflows com trigger_source: crm — separado deste nó. Veja Automatizar o CRM com workflows.

Referência técnica

Execução interna (simplificada):

{
  "workflowId": "uuid",
  "payload": { },
  "environment": "prod",
  "triggerSource": "manual"
}

O conteúdo do payload é o que o cliente envia da gaveta de teste ou do endpoint de execução manual.

Artigos relacionados

• Visão geral dos gatilhos
• Gatilho Webhook
• Gatilho Schedule
• Testar e depurar workflows
• Histórico de execuções
• Variáveis no workflow