Gatilho Schedule

O nó Schedule (schedule_trigger) inicia um workflow em um horário fixo — uma vez ou em um cronograma recorrente. Use-o para relatórios diários, lembretes de follow-up, sincronizações noturnas e qualquer automação que deva rodar sem chamadas HTTP externas.

Na paleta do editor ele aparece como Agendamento (rótulo da UI em português). Workflows legados ainda podem referenciar cron_trigger; o engine trata como o mesmo tipo de nó.

Abra Automações → paleta Triggers → Schedule / Agendamento.

Figura 1: Gatilho Schedule — cron recorrente ou data/hora única

O que ele faz

Um job cron em segundo plano (POST /workflows/cron/process-scheduled) varre workflows ativados cujo next_execution_at já passou, enfileira a execução com trigger_source: cron e recalcula o próximo slot para agendamentos recorrentes.

Configuração — passo a passo

1. Adicionar o nó Schedule

1. Abra o editor do workflow.
2. Arraste Schedule / Agendamento de Triggers para o canvas.
3. Conecte-o ao restante do fluxo.
4. Um nó de agendamento por workflow é recomendado — múltiplos nós cron não são suportados no nível do banco (cron_expression e next_execution_at são campos únicos no workflow).

2. Escolher o tipo de agendamento

3a. Recorrente — expressão cron

1. Selecione Recurring.
2. Use o construtor visual de cron ou informe uma expressão cron de 5 campos:

┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12)
│ │ │ │ ┌───── day of week (0–6, Sunday = 0)
│ │ │ │ │
* * * * *

Exemplos comuns (interpretados no fuso horário da empresa):

Os modos do construtor incluem: diário, diário com múltiplos horários, dias úteis, semanal, mensal, a cada N minutos e expressão bruta personalizada.

3b. Executar uma vez — data/hora

1. Selecione Run once.
2. Escolha Date and time (scheduled_at) no seletor de data/hora.
3. Deve ser no futuro ao salvar — horários no passado não agendam execução.
4. Após a execução concluir, next_execution_at é limpo (sem repetição).

4. Salvar e ativar

1. Save o workflow — ao salvar deriva:
   • triggers_enabled.cron: true
   • cron_expression ou scheduled_at
   • schedule_type
   • next_execution_at (calculado em UTC)
2. Ative o toggle Active — workflows inativos são ignorados pelo agendador.
3. Confirme next_execution_at nas configurações do workflow ou aguarde a primeira execução.

5. Verificar a execução

1. Abra Execution history após o horário agendado.
2. Verifique trigger_source = cron na linha da execução.
3. Inspecione a saída de cada nó se a execução falhou silenciosamente (ex.: instância ausente).

Comportamento do cron e fuso horário

• Os campos do cron são avaliados no fuso horário da empresa (companies.timezone).
• next_execution_at é armazenado em UTC no banco de dados.
• Se o fuso horário da empresa não estiver definido, o engine usa America/Sao_Paulo por padrão.
• Mudanças de horário de verão são tratadas via cálculo com consciência de fuso ao computar a próxima ocorrência.

Após cada enfileiramento bem-sucedido:

• Recorrente: next_execution_at avança para a próxima correspondência do cron.
• Uma vez: next_execution_at torna-se null.

Dados do gatilho nos nós seguintes

Execuções agendadas recebem um payload mínimo:

{
  "trigger": true,
  "scheduled": true
}

Use variáveis system para lógica sensível ao tempo:

Para workflows disparados pelo CRM que reutilizam o mesmo fluxo, o engine pode entrar via schedule_trigger quando trigger_source é crm — projete fluxos que não dependam apenas de campos de webhook.

Workflows com múltiplos gatilhos

Você pode combinar Schedule com Webhook e Manual em um workflow:

{
  "triggers_enabled": {
    "webhook": true,
    "manual": true,
    "cron": true
  }
}

• Tráfego HTTP usa webhook_trigger.
• Execuções agendadas usam schedule_trigger / cron_trigger.
• Testes manuais usam manual_trigger.

Cada origem ativa apenas seu nó de entrada correspondente.

Dicas e boas práticas

• Um cron por workflow — agendamentos diferentes exigem workflows separados (ou lógica condicional dentro de uma única execução diária).
• Horários fora de pico — agende envios em massa e jobs de sincronização fora do horário comercial para reduzir contenção na fila.
• Evite cron abaixo de um minuto salvo necessidade — agendamentos muito frequentes aumentam contagem de execuções e custo.
• Teste com Manual primeiro — valide conteúdo de mensagens e integrações antes de esperar o cron.
• Monitore falhas — jobs recorrentes falham silenciosamente se a instância estiver desconectada; adicione notificações de erro via nós HTTP ou e-mail.
• Lógica de feriados — o cron não ignora feriados nativamente; adicione uma Condition que consulta uma API de calendário ou verifica uma lista estática.
• Prevenção de duplicatas — se uma execução sobrepõe o próximo slot, a plataforma ainda enfileira conforme o agendamento; projete etapas idempotentes.

Exemplos de casos de uso

Resumo diário de vendas para a equipe

1. Schedule: 0 8 * * 1-5 (dias úteis às 08:00).
2. HTTP request → API interna do dashboard com métricas de ontem.
3. Send message para o grupo de gestores com {{input.data.total}}.

Lembrete semanal de leads inativos

1. Schedule: 0 10 * * 1 (segundas às 10:00).
2. CRM — Get cards da coluna "Stalled".
3. Loop sobre os cards → Send message com texto personalizado dos campos do card.

Broadcast pontual de lançamento de produto

1. Tipo de agendamento: Run once — data/hora do lançamento.
2. Send message estilo campanha ou iterar contatos de uma tag via Loop.
3. O workflow permanece ativo, mas o cron não dispara novamente após a execução única.

Sincronização noturna com ERP

1. Schedule: 0 2 * * * (02:00 diariamente).
2. HTTP request / nó ERP → buscar novos pedidos.
3. Loop → CRM criar/atualizar cards; Contact upsert.

FAQ

Por que meu workflow não executou no horário agendado?
Verifique: (1) workflow está active, (2) triggers_enabled.cron é true, (3) existe um nó Schedule na definição, (4) next_execution_at está no passado, (5) o fuso horário da empresa corresponde à sua expectativa.

Posso agendar a cada 30 segundos?
O cron suporta granularidade de minuto (*/1 é o passo mínimo no cron padrão de 5 campos). Agendamento abaixo de um minuto não é suportado.

O que acontece se eu excluir o nó Schedule?
Ao salvar, a plataforma limpa cron_expression, scheduled_at e next_execution_at.

O agendamento respeita a conexão da instância?
A execução inicia de qualquer forma; nós Send message falham se a instância WhatsApp estiver offline — verifique os logs de execução.

Recorrente vs legado trigger_type: cron
Workflows antigos usavam um único campo trigger_type. Workflows modernos usam triggers_enabled derivado dos nós. Ambos os caminhos convergem no agendador.

Eventos de CRM podem usar o nó Schedule?
Eventos de board CRM (trigger_source: crm) preferem schedule_trigger como entrada se presente — em geral você usa Manual ou Webhook para fluxos ligados ao CRM; veja Automatizar o CRM com workflows.

Como pausar um agendamento sem excluir o workflow?
Desative o workflow — o agendador ignora entradas desativadas.

Referência técnica

Ponto de entrada do agendador (interno): POST /workflows/cron/process-scheduled.

Payload de enfileiramento da execução:

{
  "workflowId": "uuid",
  "payload": { "trigger": true, "scheduled": true },
  "environment": "prod",
  "triggerSource": "cron"
}

Artigos relacionados

• Visão geral dos gatilhos
• Gatilho Webhook
• Gatilho Manual
• Variáveis no workflow — {{system.*}} e datas
• Histórico de execuções
• Testar e depurar workflows