---
title: "Preview Triggers"
method: POST
path: "/api/ai-agents/triggers/preview"
tags: ["ai-agents", "ai-agents"]
---

# Preview Triggers

`POST /api/ai-agents/triggers/preview`

## 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/ai-agents/triggers/preview`
- Auth: none declared

Read-only "which agent fires here" preview.

Mirrors the trigger-router's matching logic without writing to
`ai_agent_activity_log` and without executing any agent. Returns
every candidate in evaluation order plus the skipped triggers with
reasons — drives the panel on /ai-agents, the per-card footer on
/livechat, and the per-thread modal in chat.

Three event_kinds in v1:
- `incoming_call`: ring-time pickup. Calls `preview_pickup_matches`
  which mirrors `resolve_voice_pickup_trigger`. channel_type MUST
  be a voice channel.
- `incoming_message`: any new message (text DM or transcript turn).
  Calls `preview_message_matches` via `_match_triggers`.
- `blockchain`: blockchain transfer event. Same path as
  incoming_message with a synthesized blockchain event_type.

Returns 400 on missing required inputs (see slugs below). Empty
`matched=[]` is a valid response (e.g. workspace has zero
blockchain triggers).

## Request body

- TriggerPreviewRequest
  - `event_kind` 'incoming_call' | 'incoming_message' | 'blockchain', required
  - `channel_type` string, nullable
  - `channel_account_id` integer, nullable
  - `thread_id` integer, nullable
  - `thread_kind` 'dm' | 'group' | 'channel' | 'livechat' | 'voice_call', nullable
  - `message_text` string, nullable
  - `from_id` string, nullable
  - `blockchain_tx_data` object, nullable

## Response `200`

Successful Response

- TriggerPreviewResponse
  - `matched` PreviewMatch[], required
    - `rank` integer, required
    - `agent_id` integer, required
    - `agent_name` string, required
    - `agent_priority` integer, required
    - `trigger_id` integer, nullable, required
    - `trigger_type` string, required
    - `trigger_priority` integer, required
    - `specificity_score` integer, required
    - `send_mode` string, nullable, required
    - `conditions_summary` object, required
    - `handoff_agent_id` integer, nullable
    - `handoff_agent_name` string, nullable
    - `handoff_agent_status` string, nullable
  - `skipped` PreviewSkip[], required
    - `agent_id` integer, required
    - `agent_name` string, required
    - `trigger_id` integer, nullable, required
    - `reason` string, required
    - `detail` string, nullable
  - `unsimulated_gates` string[], required

## Other responses

- `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)