---
title: "Create Trigger"
method: POST
path: "/api/v1/agents/{agent_id}/triggers"
tags: ["Agents"]
---

# Create Trigger

`POST /api/v1/agents/{agent_id}/triggers`

## Request

- Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dialogbrain.com/api/v1/agents/{agent_id}/triggers`
- Auth: none declared

Attach a trigger to an agent and return it.

A voice widget needs one `incoming_call` trigger whose `conditions.channel_types` contains `livechat_voice`; without it a minted room has nobody to answer it.

## Path parameters

- `agent_id` integer, required

## Request body

- TriggerCreateRequest
  - `trigger_type` 'incoming_message' | 'incoming_call' | 'schedule' | 'webhook' | 'event' | 'blockchain_event' | 'job_completed' | 'calendar_event' | 'lead_captured', required: What makes this agent run. The allowed values are listed on this field; for a voice widget use `incoming_call`.
  - `conditions` object, nullable: When the trigger fires, as a JSON object. For a voice widget the field that matters is `channel_types`, e.g. ["livechat_voice"]; add `channel_account_ids` to narrow it to one widget instead of every widget in the workspace. Message triggers also accept `keywords` and `keyword_match` ("any" or "all").
  - `thread_ids` unknown[], nullable: Restrict this trigger to specific conversations, by numeric thread id. Applies to message and job-completion triggers only.
    - unknown
  - `blocked_sender_ids` unknown[], nullable: People this agent must never answer, by phone number, username or address. Beats every other filter, and works for calls as well as messages.
    - unknown
  - `excluded_thread_ids` unknown[], nullable: Conversations this trigger never fires in, by numeric thread id. An exclusion always wins over `thread_ids`. Applies to message and job-completion triggers only.
    - unknown
  - `send_mode` 'auto' | 'draft', nullable: Send mode override for this trigger. OMIT to inherit from the agent.
  - `enabled` boolean, nullable: Whether the trigger is enabled. OMIT to use the default (true).
  - `priority` integer, nullable: Trigger priority — lower numbers run first (default: 100)
  - `target_session` string, nullable: For an agent that delegates to Claude Code: which of your connected sessions this trigger runs on.

## Response `201`

Successful Response

- unknown

## Other responses

- `404`: No agent with this id in the workspace.
- `422`: Validation Error

---

[API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/77bef09a9209?raw)