Plataforma

Gatilhos

Um gatilho (trigger) é o que inicia um fluxo. Cada fluxo declara um único tipo de gatilho — a porta pela qual algo do mundo real pede que o fluxo rode. O Daguito tem dez tipos, cada um com seu contrato de dados.

O que é um gatilho?

Um gatilho é a fonte de um evento de entrada. Ele não faz trabalho: apenas recebe o sinal (uma mensagem, um webhook, um tique do relógio) e entrega ao motor uma entrada normalizada para o fluxo começar a rodar.

Os tipos vivem como um array de constantes tipado (CANONICAL_TRIGGER_TYPES), nunca como literais soltos — assim um fluxo só pode declarar um gatilho válido.

// Canonical trigger types — apps/api/src/flows/architecture.ts
const CANONICAL_TRIGGER_TYPES = [
  'message',         // inbound message from a channel
  'media',           // image / audio / document / video file
  'stream',          // real-time voice turn
  'webhook',         // external HTTP POST
  'schedule',        // cron / scheduled
  'manual',          // manual run from the dashboard or API
  'flow_completed',  // another flow finished
  'record',          // data record change (reserved)
  'timeout',         // a wait expired
  'event_delayed',   // delayed business event (abandoned cart, reminder)
] as const

Os dez tipos

Agrupados por como disparam:

A partir de uma conversa

• message — um usuário envia uma mensagem de texto de qualquer canal (WhatsApp, Instagram, o widget…). O gatilho mais comum.
• media — chega um arquivo: imagem, áudio, documento ou vídeo. Habilita OCR, análise de documentos ou descrição de imagens.
• stream — áudio de voz ao vivo (streaming). Para fluxos de voz em tempo real com transcrição e síntese.

A partir de um sistema externo

• webhook — um sistema externo faz um POST HTTP (ou abre um WebSocket) para uma URL com token. Sem auth: o token é o segredo.
• manual — disparo explícito pelo painel ou pela API. Útil para testar um fluxo ou executá-lo sob demanda.
• event_delayed — observa um evento de negócio, espera uma janela de tempo e dispara (cancelando-se se chegar outro evento). Potencia carrinho abandonado, lembretes e follow-ups sem resposta.

Do tempo e do próprio motor

• schedule — execução por cron, em um horário ou intervalo. Para relatórios, sincronizações ou campanhas programadas.
• timeout — uma espera de um nó venceu e o fluxo retoma. Por exemplo, um follow-up após vários minutos de inatividade.
• flow_completed — outro fluxo terminou e encadeia no próximo. É assim que você compõe fluxos grandes com peças pequenas.

Contrato de dados

Cada gatilho entrega um objeto tipado ao motor. Isto é o que seu fluxo recebe conforme o gatilho que declara:

message        → { text, sender, channel, session_key, metadata }
media          → { file_url, mime_type, size, sender, channel, session_key }
stream         → { stream_id, codec, sample_rate, session_key }
webhook        → { method, headers, body, source }
schedule       → { cron, last_run, scheduled_at }
manual         → { triggered_by, params }
flow_completed → { source_flow_id, execution_id, status, output }
record         → { table, action, record, old_record }   // reserved
timeout        → { node_id, wait_key, resume_at, reason }
event_delayed  → { watch_event, delay_minutes, cancel_events, payload_filter? }

Canais e gatilhos

Um canal não é o mesmo que um gatilho. O canal é a fonte (WhatsApp, Instagram, o widget, um webhook); o gatilho é o tipo de evento que inicia o fluxo. Vários canais podem produzir o mesmo gatilho: uma mensagem do widget e uma do WhatsApp chegam ambas como message.

Cada canal se conecta ao seu gatilho por meio de um adaptador, que normaliza a carga específica da plataforma em um InboundMessage antes de passá-la ao pipeline de ingestão unificado. Assim o motor nunca precisa saber de onde veio o evento.

O que vem a seguir?