Flow Triggers

Triggers define how a Flow starts. Each Flow should include a trigger step to accept inputs and kick off execution.

Built-in Triggers

• peer.message: Starts when a Peer receives a user message. The runtime can provide message content, attachments, conversation metadata, user/contact/peer metadata, and messages history.
• peer.action: Exposes a Flow as an action a Peer can invoke with configured input fields.
• api: Marks a Flow as executable through the client Flow API.
• form: Starts from a form-style input surface with configured fields.
• schedule: Starts automatically from a cron expression with optional default inputs.

Tool Webhook Triggers

Installed tools may expose dynamic webhook triggers. These appear as trigger types whose key starts with webhook., followed by the tool trigger ID.

• When a Flow containing a webhook.<toolTriggerId> trigger is saved, Cognipeer registers the webhook through that tool trigger.
• When the trigger is removed, Cognipeer unregisters the webhook when the tool supports cleanup.
• Use the HTTP Request step for outbound webhooks from a Flow to an external system.

Execution via API

You can start a Flow with API calls.

• Dashboard/internal execution:

  • POST /v1/flow/execute/:flowId
  • Body: { "inputs": { ... }, "returnExecutionMetadata": true }
  • Auth: authenticated user with Flow run permission

• Client API execution:

  • POST /v1/client/flow/:flowId/execute
  • Body: the input object directly
  • Requires the Flow to contain an api trigger
  • Auth: client/API context

• Execute Flow (Public Token):

  • POST /v1/flow/share/execute/:token
  • Body: the input object directly

Trigger Context

When a trigger fires, Flow execution receives a context with:

• _trigger: { type: string, data: any }
• messages: For peer.message triggers, an array of message objects derived from the incoming data
• Any inputs passed by API, form, webhook, or schedule data

Use these in expressions like { {_trigger.data} } or { {str(messages)} } to feed downstream steps.

Best Practices

• Include at least one trigger step and connect its nextStepId to the first processing step.
• Use an api trigger for Flows that must run through /v1/client/flow/:flowId/execute.
• Validate webhook and API payloads early, often with a Guardrail, Condition, or Execute Node.js step.
• For schedules, provide default inputs in the schedule trigger data.