API, Webhook e Cron | Canvas Flow

Autenticação

As rotas de execução aceitam `Authorization: Bearer <token>`, `x-api-key` ou `x-canvas-flow-token`. Para uso externo, gere uma API key no Canvas Flow em vez de expor o token master do servidor.

curl -X POST "http://localhost:3333/api/canvas-flow-api-keys" \
  -H "Authorization: Bearer <CANVAS_FLOW_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "site-widget",
    "agentId": "default-agent"
  }'

A resposta de criação mostra o token uma única vez. Guarde em secret manager ou variável segura do ambiente que vai chamar a API.

Consumir a API do Canvas Flow

Use `POST /api/canvas-flow/test` para executar um flow salvo ou uma configuração inline. Para conversas, envie `conversationId`; para contexto inicial, envie `slots`; para execução assíncrona com fila habilitada, envie `async: true` ou `queue: true`.

curl -X POST "http://localhost:3333/api/canvas-flow/test" \
  -H "Authorization: Bearer <CF_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "default-agent",
    "flowId": "<FLOW_ID>",
    "text": "Olá, preciso de ajuda",
    "conversationId": "cliente-123",
    "channel": "webWidget",
    "slots": {
      "origem": "site"
    }
  }'

`text`

Mensagem atual do usuário. Também vira `context.input` e `context.slots.userInput` durante a execução.

`conversationId`

Chave de memória e continuidade. Reutilize para preservar estado, slots e flow ativo.

`approvals`

Objeto opcional para continuar fluxos pausados em nodes de aprovação humana.

Webhook customizado

Adicione um componente Webhook em modo inbound. O Canvas Flow expõe `GET` e `POST` em `/api/canvas-flow/webhook/custom/:flowId/:webhookId`, valida o segredo configurado no node e injeta o evento em `context.slots.webhook`.

curl -X POST "https://seu-host/api/canvas-flow/webhook/custom/<FLOW_ID>/pedido-criado" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <WEBHOOK_SECRET>" \
  -d '{
    "text": "Novo pedido recebido",
    "conversationId": "pedido-9842",
    "slots": {
      "pedidoId": "9842",
      "total": 199.9
    }
  }'

Inbound

Recebe evento externo, cria o payload `webhook` nos slots e pode iniciar no node Webhook ou no início do flow.

Outbound

Envia dados do contexto para outro endpoint quando o fluxo precisa notificar um sistema externo.

Listener

Funciona como ponto de escuta dentro do fluxo quando a arquitetura pede fire-and-forget ou callback posterior.

Cron e rotinas agendadas

Use o componente Cron para disparar fluxos por intervalo, diariamente, semanalmente ou mensalmente. O runtime pode varrer crons automaticamente quando `cronAutorun` estiver ativo, ou você pode chamar a rota de execução manualmente.

curl -X POST "http://localhost:3333/api/canvas-flow/cron/run-due" \
  -H "Authorization: Bearer <CANVAS_FLOW_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "default-agent",
    "dryRun": false
  }'

Modos

Intervalo em minutos/horas, diário, semanal ou mensal, com timezone configurável.

Entrada

`cronInputText` define a mensagem usada para iniciar a execução e `cronSlotsJson` injeta slots iniciais.

Operação

`CANVAS_FLOW_CRON_AUTORUN` e `CANVAS_FLOW_CRON_SCAN_MS` controlam a varredura automática no runtime.