Flow Triggers

Flows can be triggered in several ways depending on the use case. The trigger determines when a flow starts and what input data it receives.

Trigger types

Manual trigger

Flows can be started explicitly by calling the RunFlow action or through the API:

POST /v1/apps/{appUid}/actions/call
{
  "actionIdentifier": "{blueprint}/actions/{runFlowAction}",
  "input": { ... },
  "waitForResult": true
}

Manual triggers are used for:

• User-initiated actions in the UI (for example, clicking a "Run" button)
• Programmatic invocation from external systems via the API
• Testing flows during development

Conversation trigger

The most common trigger for agent flows. The flow engine automatically starts a flow when:

1. A conversation is created with an agent participant that has autoRespond enabled — the agent's default flow starts immediately
2. A message is posted in a conversation with an auto-responding agent — if no flow is currently running for that agent in that conversation, the default flow starts; if a flow is already running, the message is routed to it

This is the primary mechanism that powers agent behavior. When a user sends a message to an agent, the conversation trigger starts the agent's flow, which processes the message and generates a response.

Event trigger

Flows can be triggered by events from external systems or from within the platform:

• Webhook events — an external system POSTs data to a webhook URL, which triggers a flow
• Platform events — internal events (for example, a record created, a task completed) trigger a flow
• Polling events — the platform detects new data from a polled endpoint and triggers a flow

Event triggers enable reactive workflows — flows that run automatically in response to changes in connected systems.

To set up an event trigger:

1. Define an event channel in the integration (webhook, SSE, or HTTP polling)
2. Subscribe the app to the relevant event
3. Configure a flow to run when the event is received

See Event Channels for details on setting up event sources.

Scheduled trigger

Flows can be triggered on a schedule (time-based). Scheduled triggers are useful for:

• Periodic data synchronization with external systems
• Regular report generation
• Cleanup and maintenance tasks

Input data

Each trigger type provides different input data to the flow:

The flow's inputSchema defines what data it expects. The trigger must provide data that matches this schema.

Combining triggers

A single flow can support multiple trigger types. For example, a flow that processes customer inquiries could be:

• Triggered by conversation when a user messages an agent
• Triggered by webhook when an external ticketing system sends a new ticket
• Triggered manually when a support agent wants to run it on a specific inquiry

The flow's input schema should accommodate data from all expected trigger sources.

Related concepts

• Building Flows — creating the flows that triggers start
• Flow Execution — how triggered flows run
• Event Channels — setting up external event sources
• Conversations — the messaging system that generates conversation triggers