Trigger Types
- The three trigger types available: temporal, hook, and manual
- How each trigger type works and when to use it
- How to configure the trigger in the Trigger section of the workflow form
A trigger is the condition that starts your workflow. Every workflow has exactly one trigger, and you select it from the Type dropdown in the Trigger section of the workflow creation form. There are three trigger types to choose from.
Temporal -- scheduled triggers
A temporal trigger runs your workflow on a schedule, similar to a cron job. Use this when you want your workflow to execute at a specific time or on a recurring interval.
Examples of temporal triggers:
- Run every weekday morning at 9:00 AM to send appointment reminders
- Run once a week on Monday to generate a summary report
- Run every hour to check for stale conversations
When you select the temporal trigger type, the form displays fields where you define the schedule as an iCalendar recurrence rule: dtstart (the first occurrence, a date-time), repeats (whether it recurs), and rrule (the recurrence rule, e.g. FREQ=DAILY;INTERVAL=1 or FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR). There is no separate cron or timezone field -- scheduling is expressed entirely through the RRULE anchored on dtstart.
Temporal triggers are ideal for recurring tasks that do not depend on a specific event happening in the system. Think of them as scheduled tasks that run like clockwork.
Hook -- event-based triggers
A hook trigger fires when a specific event occurs in the system. Use this when you want your workflow to react to an event such as a new message arriving or a contact being created.
Examples of hook triggers:
- A new message is received in a conversation
- A new contact is created in the database
- A conversation is opened from a specific channel
- An appointment or event is scheduled or updated
When you select the hook trigger type, you specify the model (the collection to watch, e.g. contacts) and the op -- the lifecycle operation that fires the hook. The op is one of beforeSave, afterSave, beforeCreate, afterCreate, beforeUpdate, afterUpdate, beforeDelete, or afterDelete (before* hooks fire before the write and after* hooks fire after it completes). In both cases the workflow receives a read-only snapshot of the document -- a workflow can never modify or cancel the write that triggered it, and a failing workflow never blocks the write.
The changed document is then available to your workflow steps as the CEL variable doc (with prev for the previous state on updates, plus op and model). For example, reference the new record's name with {"expr": "doc.name"}. Note that contact, conversation, and contactMessage are only populated when a workflow runs with a messaging/parent context (such as a workflow invoked from an assistant); for a plain hook trigger they are empty, so read the triggering record through doc. There is no top-level trigger variable.
You can also set an optional CEL filter expression on the hook trigger to narrow which changes fire the workflow. It is evaluated against the same doc and prev variables and must evaluate to true for the workflow to run -- if it returns false or fails to evaluate, the workflow is skipped. Use it for cases like "a conversation is opened from a specific channel", where model and op alone would fire for every channel.
Hook triggers are the most common trigger type. They let your workflows respond in real time to events across the system, such as welcome messages, notifications, and data updates.
Manual -- employee-triggered
A manual trigger means the workflow does not start automatically. Instead, an employee starts it by clicking the Run button on the workflow page. Use this when you want a human to decide when the workflow should run.
Examples of manual triggers:
- An employee runs a bulk data cleanup workflow when needed
- A team lead triggers a report generation workflow on demand
- A support agent manually fires a follow-up sequence for a specific contact
When you select the manual trigger type, you can optionally define custom input fields that the employee fills in when they start the workflow. For example, you might ask the employee to enter a contact ID or select a date range before execution begins.
Important: The Run button only appears once the workflow is enabled and saved. While you are creating a new workflow, it will not be available.
Manual triggers are great for workflows that require human judgment about when to run. You can also define custom inputs so the employee provides specific data each time the workflow is started.
Choosing the right trigger
| You want to... | Use this trigger |
|---|---|
| Run an automation on a fixed schedule (daily, weekly, hourly) | temporal |
| React to an event in the system (new message, new contact) | hook |
| Let an employee decide when to run the workflow | manual |
Each workflow supports exactly one trigger. If you need the same set of steps to run for different events, create a separate workflow for each trigger type.