> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers and Events

> Configure when your agent responds

Triggers define when your agent is activated — which events from which channels cause the agent to run.

## What is a Trigger?

A trigger combines:

* **Integration** — The source platform (Zendesk, Slack, etc.)
* **Event** — The action that occurred (new ticket, message, etc.)
* **Filters** — Conditions that must be met

{/* Screenshot: Trigger configuration panel showing integration, events, and filters */}

## Available Events by Integration

### Zendesk

| Event              | Description              | Common Use              |
| ------------------ | ------------------------ | ----------------------- |
| **Ticket created** | New ticket submitted     | Respond to new requests |
| **Comment added**  | Public comment on ticket | Continue conversations  |
| **Internal note**  | Private note added       | React to agent notes    |

{/* Screenshot: Zendesk event selection */}

### Slack

| Event               | Description          | Common Use               |
| ------------------- | -------------------- | ------------------------ |
| **Channel message** | Message in a channel | Monitor support channels |
| **Direct message**  | DM to the bot        | Private support          |
| **App mention**     | Bot is @mentioned    | Explicit requests        |
| **Thread reply**    | Reply in a thread    | Continue conversations   |

### Intercom

| Event                    | Description              | Common Use             |
| ------------------------ | ------------------------ | ---------------------- |
| **Conversation created** | New conversation started | Respond to new chats   |
| **Customer replied**     | Customer sends message   | Continue conversations |
| **Assigned to Duckie**   | Routed to Duckie         | Handle assigned work   |

### Discord

| Event               | Description            | Common Use        |
| ------------------- | ---------------------- | ----------------- |
| **Message created** | New message in channel | Community support |
| **Bot mentioned**   | Bot is @mentioned      | Explicit requests |

### HubSpot

| Event                    | Description            | Common Use         |
| ------------------------ | ---------------------- | ------------------ |
| **Conversation replied** | Customer sends message | Respond to tickets |

### Plain

| Event                | Description          | Common Use             |
| -------------------- | -------------------- | ---------------------- |
| **Thread created**   | New thread started   | New support requests   |
| **Thread replied**   | Customer replies     | Continue conversations |
| **Duckie mentioned** | @mentioned in thread | Explicit requests      |

### Pylon

| Event             | Description         | Common Use             |
| ----------------- | ------------------- | ---------------------- |
| **Issue created** | New issue submitted | New support requests   |
| **Issue replied** | Customer replies    | Continue conversations |

### Custom Webhook

Custom Webhook deployments accept JSON events from your own systems. You map payload fields into Duckie runs and can optionally filter by an event type field.

<Card title="Custom Webhooks" icon="plug" href="/deployments/custom-webhooks">
  Configure a custom webhook trigger
</Card>

### Scheduler

Scheduler deployments run on a recurring schedule instead of an integration event. Choose a preset schedule, describe a schedule in plain language, or enter a five-field cron expression.

<Card title="Scheduled Deployments" icon="clock" href="/deployments/scheduled-deployments">
  Configure a recurring scheduled trigger
</Card>

## Event Filters

Narrow which events trigger your agent:

### Channel Filters

{/* Screenshot: Channel filter selection showing available channels */}

Respond only in specific channels:

**Slack:**

```
#support
#customer-questions
#sales-inquiries
```

**Zendesk:**

```
Support group
VIP Support group
Enterprise group
```

### @Mention Only

Only respond when the bot is explicitly mentioned:

{/* Screenshot: @mention only toggle */}

**When to use:**

* Shared channels where bot shouldn't respond to everything
* When you want customers to explicitly invoke the bot
* Preventing unwanted responses

### Tag Filters (Zendesk)

Respond only to tickets with specific tags:

```
Tags to include: ai-enabled, duckie-support
Tags to exclude: human-only, sensitive
```

### Group/Queue Filters

Respond only when assigned to specific groups:

```
Groups: Level 1 Support, General Inquiries
```

## Configuring Triggers

<Steps>
  <Step title="Select Integration">
    Choose the platform (Zendesk, Slack, etc.).

    Only connected integrations appear as options.
  </Step>

  <Step title="Choose Events">
    Select which events should trigger the agent.

    You can select multiple events for a single deployment.
  </Step>

  <Step title="Add Filters">
    Optionally narrow with channel, tag, or mention filters.
  </Step>

  <Step title="Save">
    Save to activate the trigger configuration.
  </Step>
</Steps>

## Multiple Events

A single deployment can respond to multiple events:

**Example: Complete Zendesk Coverage**

```
Events:
- Ticket created ✓
- Comment added ✓
- Internal note (optional)

Filters:
- Group: Support Team
- Tags: ai-enabled
```

This agent responds to new tickets AND follow-up comments, but only in the Support Team group.

## Multiple Deployments

For complex needs, create separate deployments:

**Example: Different Agents for Different Events**

| Deployment | Agent         | Events         | Filters       |
| ---------- | ------------- | -------------- | ------------- |
| Triage     | Triage Agent  | Ticket created | All           |
| Support    | Support Agent | Comment added  | Support group |
| VIP        | VIP Agent     | All events     | VIP group     |

## Event Flow

```
External Event (new message/ticket)
              │
              ▼
       Webhook Received
              │
              ▼
    ┌─────────────────────┐
    │ Find Matching       │
    │ Deployments         │
    └─────────────────────┘
              │
              ▼
    ┌─────────────────────┐
    │ Check Filters       │
    │ (channel, tags,     │
    │  mention)           │
    └─────────────────────┘
              │
              ▼
    ┌─────────────────────┐
    │ Trigger Agent Run   │
    └─────────────────────┘
```

## Best Practices

### Start Narrow

Begin with specific filters, then expand:

1. One channel, @mention only
2. Add more channels
3. Remove @mention requirement
4. Add more events

### Use @Mention for Shared Spaces

In channels where not every message needs a response:

```
Slack #general → @mention only
Slack #support → All messages
```

### Prevent Loops

Ensure filters prevent the agent from responding to its own messages:

* Duckie automatically filters bot messages
* Don't respond to internal notes you created
* Check for bot user IDs in custom integrations

### Test Before Going Live

1. Configure trigger
2. Send test messages
3. Verify only intended messages trigger the agent
4. Adjust filters as needed

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Deployment" icon="plus" href="/deployments/creating-deployments">
    Build a deployment with triggers
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations/supported-integrations">
    See available integrations
  </Card>

  <Card title="Scheduled Deployments" icon="clock" href="/deployments/scheduled-deployments">
    Run agents on a schedule
  </Card>
</CardGroup>