> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Event-Driven Triggers
> Start Duvo agents automatically when something happens in a connected service — a new email, a Linear issue, a Slack message, a file, or a record status change.
Event-driven triggers let your agents start automatically when something happens in a connected service—no manual kick-off required.
### Key Capabilities
* **Inbox triggers**: Start a Run whenever a new email arrives in Gmail or Microsoft Outlook
* **Linear triggers**: Start a Run when a Linear issue is created, updated, assigned, or commented on
* **Slack mention triggers**: Start a Run by mentioning the Duvo app in any enabled channel
* **Slack channel triggers**: Start a Run automatically from channel messages matching a pattern, or on a reaction
* **File-drop triggers**: Start a Run when a new file lands in a monitored cloud folder
* **Status-change triggers**: Start a Run when a record in HubSpot, Salesforce, Notion, or another connected tool reaches a particular state
* **Google Sheets row triggers**: Start a Run when a row's watched values change in a connected spreadsheet, including a change back to a previous value
* **Email trigger filters**: Narrow Gmail triggers by sender, subject keywords, email keywords, recipients, labels, attachments, and categories
* **Linear event filtering**: Filter by event type, team, assignee, and workflow state
* **Per-user setup**: Each team member configures their own trigger using their own connected account (Slack and Microsoft Teams channel triggers can also run on a connection a teammate shared with the team)
### Trigger Types at a Glance
| Trigger type | How it fires | Typical latency | Deduplication | Retry behavior | Payload size limits |
| ------------------------------------------- | --------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email — new message | Polling (inbox check) | Depends on the configured schedule interval | Duvo tracks processed trigger items so each matching message starts once | Polling retries on the next schedule run if the current run fails | N/A — not exposed |
| Email — filtered message | Polling, filtered | Depends on the configured schedule interval | Same as email trigger | Same as email trigger | N/A — not exposed |
| Linear — new issue / state change / comment | Push (webhook) | Seconds | Each event fires once | Linear retries webhook delivery on failure | N/A — not exposed |
| Slack mention | Push (Slack event) | Seconds | Each mention fires once | Slack retries event delivery | N/A — not exposed |
| Slack channel message | Push (Slack event) | Seconds | Each matching message fires once | Slack retries event delivery | N/A — not exposed |
| Slack reaction | Push (Slack event) | Seconds | Each reaction fires once | Slack retries event delivery | N/A — not exposed |
| File drop in cloud folder | Polling | Depends on configured schedule interval | Use Agent Memory to track already-processed files | Polling retries on next schedule run if current run fails | N/A — not exposed |
| API-triggered (sandbox upload) | Push (HTTP POST) | Seconds | Caller is responsible for deduplication | No automatic retries — caller must retry on failure | See [Running Agents via API](/user-guide/running-assignments/running-assignments-via-api) |
| CRM / PM status change | Polling | Depends on configured schedule interval | Use Agent Memory to track last-seen state | Polling retries on next schedule run if current run fails | N/A — not exposed |
| Google Sheets row change | Polling | Depends on the configured schedule interval | Fires when a row's watched values differ from the last-checked values, including reverts | Polling retries on the next schedule run if the current run fails | Watch window caps at 5,000 rows and 250,000 cells combined (columns × rows), with row numbers up to 10,000,000; up to 250 changed rows processed per check |
For details on each trigger type beyond inbox and Linear, see the linked guides below.
***
### How to Use It
Open your agent in the Duvo workspace and navigate to the **Setup** tab.
Find the connection that supports triggers in the Connections section.
Toggle the trigger on. A settings modal opens automatically.
Choose which events or senders should start a Run.
Click Save. The trigger is now active.
To pause a trigger, toggle it off. To change the filters, toggle it off and back on to re-open the modal.
***
### Supported Connections
| Connection | Trigger Event | Available Filters |
| ----------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| Gmail | New email received | Senders, subject keywords, email keywords, recipients, labels, attachments, categories |
| Microsoft Outlook | Email received | Sender email address, folder, shared mailboxes |
| Microsoft Outlook | Email sent | Recipient (To) address, shared mailboxes |
| Linear | New issue created | Team, assignee, workflow state |
| Linear | Issue workflow state changed | Team, assignee, destination state |
| Linear | Issue assigned | Team, assignee |
| Linear | New comment posted | Team, issue assignee |
| Slack Workspace | Mention of the Duvo app in a channel | Agent selection |
| Slack Workspace | New message in a channel | Channel, keywords or patterns |
| Slack Workspace | Reaction added to a message | Channel, reaction emoji |
| Google Sheets | Row's watched values change | Columns (required), row range (required), tab, key column |
***
### Configuring a Linear Trigger
When you enable a Linear trigger, a settings modal lets you specify:
* **Start work when**: Choose one of the four event types — new issue, state change, agent, or new comment.
* **Team** (optional): Enter one or more Linear team keys (for example, `ENG` or `DESIGN`) to restrict the trigger to issues from those teams. Leave empty to match all teams.
* **Assignee** (optional): Enter one or more Linear user IDs, or `me`, to restrict the trigger to issues assigned to specific people. Leave empty to match any assignee.
* **Workflow state** (optional, for new issue and state change events): Select one or more states (Triage, Backlog, Unstarted, Started, Completed, Canceled). Leave empty to match any state.
The trigger uses the Linear account you have connected under your profile. Each team member must enable the trigger individually using their own connection.
***
### Email Trigger Filters
By default, an email trigger fires on every new message in the connected inbox. You can narrow Gmail triggers by sender, subject keywords, email keywords, recipients, labels, attachments, and Gmail categories. Outlook filters vary by trigger type.
**How to configure:**
Enable the Gmail or Outlook trigger in **Setup**.
In the trigger settings modal, add one or more filter values:
* **Specific address** — for example, `orders@acmecorp.com`
* **Domain** — for example, `@acmecorp.com` to match all addresses at that domain
* **Subject keywords** — for example, `Invoice` to match emails whose subject contains the word
* **Label** — for example, `Finance` to match emails Gmail has tagged with that label
* **Has attachment** — toggle on to match only emails with an attachment
Save. The trigger now fires only when an email matches the configured filters.
**When to use this:**
* An order-intake agent that should only fire for emails from known supplier addresses, not all incoming messages
* A vendor alert agent scoped to one specific vendor's notification domain
* Combining with subject or body filtering in your AOP to further narrow what the agent acts on
**Worked example — supplier order intake:**
```
Trigger: New email from @acmecorp.com OR @betasupply.com
AOP: For each matching email, extract the order fields and create a record in your ERP.
Emails from other senders land in the inbox but do not start a Run.
```
***
### When to Use It
* **Customer request processing**: Start a Run automatically when a customer emails a support address
* **Order intake**: Kick off purchase order processing when an order email arrives from a known supplier
* **Issue triage**: Start a Run when a new Linear issue lands in Triage so it can be automatically classified, enriched, or routed
* **Workflow automation**: Trigger a Run when a Linear issue moves to a specific state, such as starting downstream work when an issue enters "In Progress"
* **Report distribution**: Trigger data collection or summary runs when a scheduled report lands in your inbox
* **Vendor alerts**: React to supplier notifications or price change emails as Duvo checks the inbox
### How It Works
When you enable a trigger, Duvo monitors the connected service for matching events. When an event occurs, Duvo starts a new Run for your agent and passes the event details as context. Your agent's AOP then processes the event and carries out the workflow.
Email triggers check your connected inbox on a schedule. Linear triggers listen for webhook events from your Linear workspace.
```mermaid theme={"dark"}
flowchart TD
A[Event in connected service] --> B{How does the trigger fire?}
B -->|Push: Linear, Slack| C[Duvo receives the event in seconds]
B -->|Polling: email, file drop, status change| D[Duvo checks the service on a schedule]
C --> E{Matches your filters?}
D --> E
E -->|No| F[No Run started]
E -->|Yes| G[Deduplicate: each matching item starts once]
G --> H[Start a new Run, pass event details as context]
H --> I[Agent AOP processes the event]
```
***
### Slack and Microsoft Teams Triggers
Slack and Microsoft Teams each present their triggers as two separate rows in the Connections section — an **@mention** row and a **channel** row (Teams labels the second as channels or conversations).
**@mention triggers** — Mention the Duvo app in any enabled channel to start a Run on demand. The agent runs and posts results back to the same thread. An @mention trigger always runs as the mentioning user, so it uses that user's own personal connection. See [Slack Mention Workflows](/user-guide/examples/slack-mention-workflows) for a full guide.
**Channel triggers** — Start a Run automatically from any message (or messages matching a keyword pattern) in a channel, without anyone needing to mention the Duvo app. Useful for monitoring channels like #alerts or #support-inbox. When you create a channel trigger, a connection picker lets you choose which connection backs it. If your organization has Connections sharing enabled, the picker groups connections into **Team** (shared) and **Personal** sections, and a channel trigger can run on a team-shared connection. See [Slack Channel Triggers](/user-guide/assignment-features/slack-channel-triggers) for setup and examples.
***
### File-Drop Triggers
Start a Run whenever a new file lands in a monitored cloud folder (Google Drive, OneDrive, SharePoint) or arrives as an attachment in your inbox. Useful for invoice processing, document validation, and any workflow where the input arrives as a file rather than a message. See [File-Drop Triggers](/user-guide/assignment-features/file-drop-triggers) for setup and a worked example.
***
### Status-Change Triggers
Start a Run when a record in a CRM or project management tool reaches a particular stage — for example, when a HubSpot deal moves to "Closed Won" or a Notion page status changes to "Ready for Review". Implemented by scheduling an agent to poll the service and using Agent Memory to track what it last saw. See [Status-Change Triggers](/user-guide/assignment-features/status-change-triggers) for setup and examples.
***
### Google Sheets Row Triggers
Start a Run when a row's watched values change in a connected spreadsheet — including when a value changes back to what it was before. Both a column range and a row range are required, so the trigger always watches a bounded area of the sheet rather than the whole thing. See [Google Sheets Triggers](/user-guide/connections/available-connections/google-sheets#triggers) for field details and limits.
***
### What Is Not Supported Today
Be aware of these gaps when planning your trigger setup:
Duvo does not currently expose a dedicated URL that external systems can POST events to. **To start a Run when an external system fires a webhook** (for example, a form submission service, payment processor, or custom app), set up a lightweight webhook handler on your side that calls the [Duvo API](/user-guide/running-assignments/running-assignments-via-api) `POST /teams/{teamId}/runs` endpoint. Pass the event payload as the run context. Retry logic, signing secret verification, and payload mapping are handled by your webhook handler, not by Duvo. See [Running Agents via API](/user-guide/running-assignments/running-assignments-via-api) for the full run API reference.
Status-change triggers for these tools use scheduled polling, not real-time webhooks. Latency depends on your polling schedule — typically 5 to 60 minutes.
Duvo cannot watch a local folder or network drive. Files must be in a cloud storage service (Google Drive, OneDrive, SharePoint) or arrive via email attachment.
Status-change detection for Jira uses scheduled polling.
An agent with multiple trigger types enabled must use a single AOP for all triggers. You cannot assign different AOPs to different trigger types on the same agent.
***
### API Trigger
Every agent can also be started via the Public API. The Triggers section of the Setup tab includes a collapsed **API trigger** card that shows a ready-to-use curl example pre-filled with your agent's ID:
```bash theme={"dark"}
curl -X POST https://api.duvo.ai/v2/teams/{teamId}/runs \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"agent_id": "", "message": "Optional first message"}'
```
The `message` field is optional — include it to pass an initial prompt to the agent when starting the Run. API keys can be created under **Your Profile → API keys** (scoped to a single team or to all teams you can access), or under **Team Settings → API keys** by users with the Manager role or above.
For a full reference of run options (sandbox files, webhooks, and polling), see [Running Agents via API](/user-guide/running-assignments/running-assignments-via-api).
### Related Features
Run agents on a recurring time-based schedule instead of (or in addition to) event-driven triggers.
Start Runs from new files in cloud folders or inbox attachments.
Start Runs when CRM or project management records change state.
Start Runs from channel messages without mentioning the Duvo app.
Connect your Gmail account.
Connect your Outlook account.
Connect your Linear workspace.
Install the Duvo app in your Slack workspace.
Connect Google Sheets and set up row-change triggers.