> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Triggers
> Automate agents with schedule, event, and webhook triggers
## What are triggers?
A Trigger is an event that automatically starts an Agent, transforming it from an on-demand tool into a proactive agent running in the background. You can set up Triggers to run Agents based on a schedule, specific events in your other software, or incoming webhooks.
A Trigger is not required if you only plan to run an Agent manually.
## Organize triggers with tags
Use trigger tags to label related triggers by team, workflow, customer, or purpose. Tags are shared across your workspace and can be created, renamed, recolored, or deleted from the tag picker on any trigger.
On the main Triggers page, use the Tags section in the sidebar to filter the list. Selecting more than one tag shows triggers that have any selected tag.
## How to create triggers
All trigger types include a **Timeout** setting. Choose 15, 30, 60, or 120 minutes, or choose **Uncapped** for runs that should not stop automatically. If you do not change this setting, Realm stops a trigger run after 60 minutes.
### Based on a schedule
This trigger runs an Agent on a recurring, time-based interval. You can set it to run daily, weekly, or monthly.
**Example**: An Agent could run every morning at 8 AM, scan your calendar for the day's meetings, gather recent news and background information on the attendees and their companies, and deliver a concise briefing document.
### Based on a knowledge event
This trigger runs an Agent automatically when synced knowledge changes in one of your connected systems. Use it when the Agent should react to new or updated records, documents, messages, tickets, calls, CRM objects, or activities.
When you create a knowledge-event trigger, you define what starts the Agent, where it happens, and under what conditions. The configuration options are:
* **Source**: The connected application where the event originates, such as Gong, Salesforce, HubSpot, Slack, Google Drive, Jira, or Zendesk. Only connected sources are shown.
* **Trigger when**: The item type and change type that starts the Agent. Realm builds these options from the selected source's supported content types, such as Opportunity updated, Deal updated, Ticket created, Call created, Thread created, or Thread reply added.
* **Filter conditions (optional)**: Rules that control precisely when the Agent runs.
* **If**: Set conditions based on the changed item. For example, only run the Agent when an Opportunity's Stage changes to Closed Won, when an Owner field is not empty, or when a call's duration is longer than 10 minutes.
* **Folder or Channel**: Restrict the trigger to a specific folder, channel, or similar location within the source application. Slack triggers require a channel. Other sources can usually be left unrestricted.
* **Bot messages**: For Slack triggers, you can restrict which bots may start the Agent. An empty allowed-bots selection blocks every bot while still allowing messages from people. A workflow always ignores Slack messages produced by its own runs, even when other Realm messages are allowed.
#### Options of the Trigger when field
After you select a Source, Realm shows the event options available for that source. Each option pairs a supported item type with the event that can start the Agent:
| Pattern | Meaning | Example options |
| ----------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Item created** | A new item of that type was synced | Opportunity created, Deal created, Call created |
| **Item updated** | An existing item of that type changed | Opportunity updated, Deal updated, Ticket updated |
| **Item reply added** or **Item activity added** | A new reply, comment, or activity was added to an existing parent item | Thread reply added, Opportunity activity added, Deal activity added |
Some item types only support updated events, so you may not see both created and updated for every item type. Salesforce also includes shortcuts such as Task created and Event created for activity-style automation.
For CRM automation, look for the CRM object in this menu rather than a separate generic event name. For example, a Salesforce Opportunity change is configured with Source = Salesforce and Trigger when = Opportunity updated. A HubSpot deal change is configured with Source = HubSpot and Trigger when = Deal updated.
#### Conditions on updated events
Updated events require at least one Filter condition. The Agent runs only when a condition field changed and the new value matches the condition.
For example, to run when a Salesforce Opportunity is moved to Closed Won:
* Source: Salesforce
* Trigger when: Opportunity updated
* Filter condition: If Stage equals Closed Won
This means the Agent runs when the Opportunity's Stage field changes to Closed Won. It does not run for every unrelated edit to the Opportunity.
Filter conditions can match a specific value, exclude a value, check whether text contains a value, match any value from a list, or check whether a field is empty or not empty.
Created and reply/activity-added events can be left without conditions. If you leave them unrestricted, the Agent runs for every new matching item in the selected Source and folder or channel.
**Example: Analyze a Gong call transcript**
Goal: Automatically summarize every new sales call, identify mentioned competitors, and extract action items.
* Source: Gong
* Trigger when: Call created
* Agent action: The Agent receives the call transcript, summarizes it, searches for competitor names against a predefined list, and sends a summary with action items to a specific Slack channel.
**Example: Automate CRM updates**
Goal: When a deal is marked as "Closed Won" in Salesforce, automatically fill in a "Win Reason" field based on recent call notes and emails.
* Source: Salesforce
* Trigger when: Opportunity updated
* Filter: If Stage equals Closed Won
* Agent action: The Agent gathers context from recent activities, generates a concise "Win Reason", and updates the corresponding field in Salesforce.
**Example: React to a new CRM activity**
Goal: When a task or event is added to a Salesforce Opportunity, summarize what changed and notify the account owner.
* Source: Salesforce
* Trigger when: Opportunity activity added, Task created, or Event created, depending on the activity you want to catch
* Filter: Optional, such as If Reply Type equals Task
* Agent action: The Agent reads the Opportunity context and the new activity, then sends a Slack message to the owner.
**Example: Sync Salesforce Opportunities to Google Sheets**
Goal: Keep a Google Sheet up to date when relevant Salesforce Opportunities are created or updated.
Set up the Agent with these pieces:
* Add Salesforce as knowledge or as a tool, depending on whether the Agent only needs synced CRM context or also needs to run live Salesforce actions.
* Add the Google Sheets tool and enable the read and write actions the Agent needs.
* Make sure the spreadsheet is selected with Google Picker before the Agent writes to it. See [Updating Google Sheets](/agents/tools#updating-google-sheets) for the detailed setup.
* Set write actions to **Ask** while testing. Change them to **On** only after the Agent reliably writes the right rows and values.
* Use preset parameters for stable values the Agent should not choose, such as the Spreadsheet ID and a fixed sheet or range pattern.
* Let the Agent fill dynamic values, such as the row to update and the cell values, when those depend on the triggered Opportunity or the current sheet contents.
Then create a trigger:
* Source: Salesforce
* Trigger when: Opportunity created or Opportunity updated
* Filter: Add conditions for the changes you care about, such as If Stage equals Proposal or If ARR Growth is greater than 100000.
* Agent instructions: Tell the Agent to read the triggered Opportunity, check whether that Salesforce Opportunity ID already exists in the sheet, then update that row or add a new row.
Use a stable unique key, such as the Salesforce Opportunity ID, to match CRM records to spreadsheet rows. Names can change and are not always unique.
Event triggers react to future create, update, and activity events as Realm syncs them. They do not bulk-import every existing CRM record. For an initial backfill, run an Agent manually or on a schedule and instruct it to search Salesforce for the records to add before the event trigger handles future changes.
### Based on a webhook
This trigger runs an Agent when it receives an HTTP request from an external system. This is a powerful way to integrate with internal tools or any third-party platform that can send webhooks, even if it doesn't have a direct integration with Realm.
To set up a webhook trigger:
1. **Select trigger type**: Choose "Based on a webhook" when creating your trigger.
2. **Copy the webhook URL**: Realm will generate a unique URL for this trigger. Copy this URL.
3. **Configure the external system**: Paste the copied URL into the webhook configuration section of the external tool you want to trigger the Agent from.
4. **Choose authentication (optional)**: Select an authentication method to secure your webhook and ensure only authorized systems can trigger your Agent.
**Example**: A "Contact Us" form on your website could send a webhook to Realm for each new submission. An Agent could then analyze the submission, create a new lead in your CRM, and notify the appropriate sales representative in Slack.
## Run history and monitoring
You can monitor a trigger from the Agents > Triggers list and from the trigger's detail page. In the list view, each trigger shows its Last run and Status, which makes it easy to scan whether a trigger is active and when it last ran.
### Trigger details page
On the trigger detail page, the Execution history section shows individual runs for that trigger. Each run includes the run time, the trigger type shown as Scheduled run, and a Completed status.
#### What you can see
* Trigger status in the list view, such as Active
* Last run in the list view
* Execution history on the trigger detail page
* Configured timeout on the trigger detail page
* Run status for each execution, such as Completed or Timed out
#### Why it is useful
Use run history to:
* Confirm that a trigger is firing as expected
* Check when the trigger last ran
* Review whether recent executions completed successfully
* Track trigger activity over time
* Manually run a trigger with its normal input, a selected document, a webhook payload, or raw text input when testing
#### Monitoring tips
* After creating a trigger, check its Status and Last run in the list view to confirm it is active and running
* Open the trigger detail page to review Execution history
* Use the history table to verify that scheduled runs are completing as expected
## Sharing and permissions
A trigger has one owner and can be shared with other people in your organization. New triggers are private to their owner until the owner shares them. Triggers that were created before sharing was introduced stay visible to everyone in your organization.
### Roles
* **Owner**: The person who created the trigger. An owner can do everything an editor can do, and can also delete the trigger, manage its access list, and transfer ownership to someone else.
* **Editor**: Can change the trigger's configuration, enable or disable it, run it now, and retry, cancel, or resume runs. An editor cannot delete the trigger, share it, or transfer ownership.
* **Viewer**: Can open the trigger and read its configuration and run history. A viewer cannot change the trigger, its tags, and cannot start a run.
Only full members and admins can be added to a trigger, because viewing, changing, and running a trigger are all full-member actions. Collaborators cannot be given access to a trigger.
### Who can see a trigger
The owner chooses between two levels of visibility from the sharing menu:
* **Private**: Only the owner and the people on the access list can see the trigger. Add people individually and choose whether each of them is a viewer or an editor.
* **Everyone in your organization**: Anyone in your organization can open the trigger and follow its runs. Changing or running the trigger still requires the editor role.
You can switch between these two options at any time, and the named people on the access list keep the roles you gave them.
### Organization admins
Organization admins can see every trigger and can pause or resume any of them without being added to the access list. When an admin needs to change a trigger, they can grant themselves edit access in one click. That grant then appears in the trigger's access list, so the owner can always see who has access.
### Runs use the owner's permissions
A trigger always runs with its owner's permissions and connections. Changes made by an editor are carried out under the owner's identity, so a run can only reach the documents, agents, and calendars that the owner can reach. Transferring ownership changes which permissions later runs use.
Run status, timing, and errors are visible to editors and viewers. The chat transcript of a run is not shared: it stays with the person whose run created it.
Because of this, an editor can only pick an agent that the owner can reach, and the Google Calendar connection of a calendar trigger can only be changed by the owner. An editor sees the owner's calendar selection but cannot swap in their own connection.
### Transferring ownership
An owner can transfer a trigger to another full member or admin of the organization. The previous owner stays on the access list as an editor, so they can keep working on the trigger without owning it. Because later runs use the new owner's permissions, a transfer is refused when the new owner cannot reach the trigger's agent, and a calendar trigger can only be transferred to someone who has access to its Google Calendar connection.
## Troubleshooting a trigger
If a trigger does not run as expected:
* Confirm the trigger is enabled
* Check that the trigger conditions are correct
* Verify that the source system is sending the event or webhook
* Review the most recent run history for errors or skipped runs
Run history gives you visibility into how your Agents behave over time, making it easier to monitor, debug, and trust automated workflows.