Workflow agent triggers

Workflow triggers start an Optimizely Opal workflow agent when their defined conditions are met. Each trigger listens for a specific event, such as a chat command, a scheduled time, a webhook call, or an email. When that event occurs, the workflow agent runs.

Important information about triggers

Connections

When configuring a trigger for your workflow agent, the trigger establishes a connection to a specific associated Optimizely instance during its creation.

If you change the connection to an associated instance after a trigger is created, the trigger may continue to reference the original instance it was configured with. This can lead to unexpected behavior or issues where the workflow agent does not interact with the intended instance.

To prevent this, ensure that your connections to all associated instances are established before creating workflow triggers. If you must change a connection, recreate any affected triggers to ensure they are correctly linked to the updated instance. See the Connections section in the Get started with Optimizely Opal for administrators documentation for information. 

Creator

A workflow agent's actions display as performed by the user who created the trigger. For example, if User1 creates a trigger and the workflow agent creates a page in Optimizely Content Management System (SaaS), User1 displays as the page's creator.

Field importance for AI

Descriptions and other configuration fields play an important role in how Opal processes workflow agents. All description fields contribute to clarity, maintainability, and future functionality. Required fields are meaningful either immediately or for upcoming platform capabilities. Because of this, you should enter complete and accurate descriptions for all fields, including those in specialized agents and tools.

Chat input trigger

A Chat input trigger is an event that starts a workflow agent when a collaborator sends a specific message or command in Opal Chat. When the workflow agent detects that a collaborator has entered specific words or patterns in the chat, it automatically starts the remainder of the workflow process.

Configure a chat input trigger

1. Enter a Name.

2. (Optional) Enter a Description.
    

   

3. Click Save.

Use cases for a chat input (message) trigger

The chat input (message) trigger is ideal for workflow agents that need to run on demand and directly from chat without requiring a manual button click or external system event. It creates a seamless experience for collaborators, letting them start complex, multi-step automations by typing a request.

Scheduler trigger

The scheduler trigger starts a workflow agent automatically at a specific time or on a recurring schedule. This is useful for workflows that run consistently without manual intervention, like sending weekly reports or syncing data every night.

Configure a scheduled trigger

1. Enter a Name.
2. (Optional) Enter a Description.
3. (Optional) Select a Product Instance. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Opal instance.
4. (Optional) Enter a Trigger Message. The trigger message is standard plain text written in natural language that the workflow sends to the next agents when the trigger occurs. No special syntax or templating language is required. Write your request exactly as you would type a chat message to an AI agent.
   • Sending the message – Type your instruction directly into the Trigger Message field. For example, The target audience is Marketers.
   • Receiving the message – The agent processes this exact text as its initial prompt and acts on its configured capabilities. If one of the following agents has an input variable of target audience, it uses the value Marketers.
5. Configure the one time trigger date or reoccurring time.
   • One time trigger
     1. Keep the Recurring toggle off.
     2. Enter a Trigger Date or click the Calendar to select a date. 

     3. Use the Trigger Time drop-down lists to select a time. Times are listed in your local time zone. 

        

   • Reoccurring – Standard
     1. Toggle Recurring on.
     2. Select the Standard tab.
     3. Enter or use the arrows to select how often the trigger occurs.
     4. Select how often the trigger occurs from the drop-down list.
     5. Select which days the trigger occurs.
     6. Select an End Type from the drop-down list.
        1. If you select Max Occurrences, enter the number of occurrences.
        2. If you select End Date, enter the end date.

     7. Review the Preview and ensure the dates and times look correct.

        

   • Reoccurring – Advanced (Cron)
     1. Toggle Recurring on.
     2. Select the Advanced (Cron) tab.
     3. Enter a Cron Expression for how often you want the trigger to occur. See Advanced (Cron) expressions for the scheduled trigger for information.
     4. Select an End Type from the drop-down list.
        1. If you select Max Occurrences, enter the number of occurrences.
        2. If you select End Date, enter the end date.

     5. Review the Preview and ensure the dates and times look correct.

        

6. Click Save.

Advanced (Cron) expressions for the scheduled trigger

Cron expressions are a standardized way to define repeating schedules. They consist of five fields that represent a time pattern.

* * * * *
| | | | |
| | | | └─ Day of week (0–6, where 0 = Sunday)
| | | └── Month (1–12)
| | └─── Day of month (1–31)
| └──── Hour (0–23)
└───── Minute (0–59)

The following table includes common cron expressions:

You can use Opal to help you formulate your cron expression.

For example, enter What would be the cron expression for running the job every night at 10 pm?

Use cases for a scheduler trigger

A scheduler trigger is ideal when you want workflow agents to

• Run consistently without requiring manual intervention to start them.
• Automate maintenance tasks like clearing old data or generating reports.
• Align with business cycles, such as monthly billing or weekly marketing updates.

By combining the scheduler with other workflow agent logic, you can create powerful, automated processes that run exactly when needed.

Webhook trigger

The webhook trigger starts a workflow agent when an external system sends an HTTP request to a unique endpoint. Use this trigger to respond to events that occur outside of Opal. For example, a content update event in Optimizely Graph, a flag update in Feature Experimentation, or a build pipeline completion event.

Configure a webhook trigger

1. Enter a Name.
2. (Optional) Enter a Description.
3. (Optional) Select a Product Instance from the drop-down list. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Opal instance.
4. (Optional) Select the Payload Content Type from the drop-down list. This specifies the format of the data (payload) the webhook expects to receive. Common types include application/json (for JSON data). See Example payload content types.
5. (Optional) Enter a Payload Schema to define the structure and data types of the expected payload. A schema helps validate incoming data and ensures the webhook processes information correctly. This is typically in JSON schema format.
6. (Optional) Enter a secret value for the Auth Key that authenticates incoming webhook requests (for example, a token or API key). This enhances security by ensuring only authorized senders can trigger the webhook.
7. (Optional) Select the Auth Header Name of the HTTP header that sends the auth key. Common examples include Authorization or X-Webhook-Secret.
8. (Optional) Enter the string template for the Auth Header Format to construct the header.

9. Click Save. 
   
   The system automatically generates the Webhook URL automatically. Copy this URL and use it in the external system.

   

Example payload content types

Use cases for a webhook trigger

Choose the webhook trigger when you want workflow agents to start immediately in response to external events, without polling or manual action. The webhook trigger works well for real-time syncs, notifications, and event-driven automation.

Email trigger

The Email trigger starts a workflow agent when an email is sent to the email address that you set as the Trigger Recipient.

The trigger activates only when

• An email is sent to the Trigger Recipient.
• The email matches the Sender Filters and optionally the Subject Filters.

This ensures that only valid or expected messages start the workflow.

The system does not support custom domains and Reply-To headers. Opal's domains use DomainKeys Identified Mail (DKIM), Domain-based Message Authentication, Reporting, and Conformance (DMARC), and Sender Policy Framework (SPF) to maintain deliverability, and the system restricts sending from arbitrary addresses for security.

Before using the email trigger, you must configure the email domain.

See Email domain configuration for information. After you set your Email Domain, you cannot update it.

Configure an email trigger

Each workflow agent can have one email address recipient. Enter the following data and click Save.

1. Enter a Short Description for the email trigger.
2. (Optional) Select a Product Instance. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Opal instance.
3. Enter the email address for the Trigger Recipient. This is the part before the "@" symbol.
   • Click Copy to copy the email address to your clipboard.
4. Define criteria to filter incoming emails based on sender's email address in the Sender Filters. Only emails matching these conditions trigger the workflow agent.
5. (Optional) Define criteria to filter incoming emails based on their subject line in the Subject Filters. Only emails matching these conditions trigger the workflow agent. For example, you can require subject lines that contain Approved or Request Details.
   • (Optional) Select Match case to limit results to text with the exact capitalization you entered.

6. Click Save.

   

Use cases for an email trigger

• Approvals and sign-offs – A reviewer sends "approve" or "deny", and the workflow agent branches accordingly.
• Vendor intake through email – A partner emails a CSV or PDF to a monitored alias, and the workflow agent starts and processes the attachment.
• Change requests with notes – A stakeholder replies that an item needs changes with comments. The workflow agent routes back to the owner.
• Lightweight ticket creation – Inbound emails trigger triage, labeling, and assignment without a separate helpdesk.

Difference between an email trigger and the send_email tool

The email trigger and the send_email tool serve different purposes.

• The Email Trigger starts a workflow agent when an email is sent to the automatically generated trigger address.
• The send_email tool sends emails from within a workflow agent. You can send these emails to any external address. It is not limited to sending messages to yourself.

Next steps

See Create a workflow agent.