事件目錄

每個 Webhook 主體都有一個 type 欄位，其值為本頁列出的其中一種事件類型。當你訂閱某個端點時，events 陣列必須包含你想要的事件類型（或留空以訂閱所有事件）。這些事件有兩種傳送方式：

端點傳送一律為具備重試機制的非阻塞式 通知：請回應任意 2xx；封裝內容含有可用於去重的 event_id。
阻塞式交換僅會在舊版單一 URL Webhook上執行：包括 telephony.incoming / web.incoming 設定請求（Webhook 模式號碼與小工具金鑰，逾時時間為 10 秒），以及 Webhook 模式的工具派送。你的回應會影響即時通話。

以下範例酬載會依傳輸順序顯示端點封裝內容（鍵依字母順序排列：data、event_id、type）；舊版傳送包含相同的 data，但不含 event_id。

通話事件

`telephony.incoming`

當來電通話抵達你的其中一個電話號碼時傳送。端點傳送是針對每一通來電通話的即發即忘通知，無論該號碼是否已設定智慧體或 webhook。未指派智慧體的號碼還會在舊版 webhook 上收到阻塞式 設定請求——完整的請求／回應結構請參閱 telephony.incoming / web.incoming。

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

當來電或撥出電信通話結束時傳送。非阻塞式。包含逐字稿、錄音 URL（如有）及計費摘要。酬載結構請參閱 telephony.complete / web.complete。

`telephony.tool`

電信通話呼叫函式工具後傳送。非阻塞式稽核通知—— 傳送此事件時，工具已執行完成；此事件涵蓋你自己的函式工具（不包括內建工具、知識庫工具、應用程式連線工具或 MCP 工具）。

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response 是執行結果：成功時為 {"status": <http status>, "response": <your endpoint's JSON>}，失敗時為 {"status": <status>, "error": "<message>"}。

`web.incoming`

telephony.incoming 的網頁頻道對應事件，當網頁小工具工作階段或建置器麥克風測試通話開始時傳送。端點傳送是針對每個網頁工作階段的即發即忘通知。 mode="webhook" 中的可發布金鑰還會在舊版 webhook 上收到 阻塞式設定請求——該阻塞式請求的格式不同（origin_domain、 publishable_key_prefix；沒有電話號碼）。請參閱 telephony.incoming / web.incoming。

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number 一律為字面值 "web"。對於 webhook 模式的小工具工作階段，to_number 為空（工作階段的智慧體號碼會在設定後指派）；對於建置器麥克風測試通話，origin_domain 和 publishable_key_prefix 為空。

`web.complete`

telephony.complete 的網頁頻道對應事件，涵蓋網頁小工具通話（direction: "web"）及建置器麥克風測試通話（direction: "test"）。非阻塞式。酬載格式與 telephony.complete相同，另加上 origin_domain，且 from_number 設為 "web"。

在舊版單一 URL webhook 中，建置器麥克風測試通話歷來會回報為 telephony.complete——只有 direction: "web" 通話會在該處使用 web.complete 類型。端點系統會將網頁及測試通話對應至 web.*。歷史酬載可能包含舊版的 direction 值 widget 或 mic。

`web.tool`

telephony.tool 的網頁頻道對應事件。data 會帶有 origin_domain，而非 from_number / to_number。

語音事件

自訂語音建立為非同步作業。這些非阻塞事件可讓你在取得最終結果時做出回應，而無須輪詢複製詳情端點。

`voice.ready`

當自訂語音完成處理並可指派給智慧體時傳送。

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

`voice.failed`

當自訂語音處理發生永久性失敗時傳送。

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

欄位	類型	說明
`voice.id`	string	自訂語音公開 ID
`voice.name`	string	格式為 `custom:<public_id>` 的智慧體語音值
`voice.display_name`	string	組織對外顯示的語音名稱
`voice.language`	string	複製語音的單一語言代碼
`voice.gender`	string	`male`、`female` 或空字串
`voice.status`	string	`voice.ready` 為 `ready`；`voice.failed` 為 `failed`
`voice.failure_reason`	string	成功時為空；失敗時為處理失敗詳情
`voice.created_at`, `voice.updated_at`	timestamp	ISO 8601 時間戳記
`reason`	string	失敗詳情；僅於 `voice.failed` 時提供

品質事件

`call.graded`

當通話的 AI 評分執行完成時發送。非阻塞。

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

欄位	類型	說明
`grade.id`	integer	評分 ID
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`、`failure`、`unknown` 或 `no_conversation`
`grade.summary`	string	單段摘要
`grade.detected_issues`	array	評分器找到的問題字串
`grade.status`	string	一律為 `completed`——僅已完成的執行會發出事件
`grade.grader_model`	string	產生結果的評分器（例如 `heuristic-v1`）
`grade.graded_at`, `grade.created_at`	timestamp

一通通話可能會被評分多次——快速啟發式評分通常會在錄音可用後，再接著進行完整模型評分，也可以手動重新評分。每個完成的執行都會發出自己的 call.graded 事件；請以最新的 graded_at 作為準據。

`issue.reported`

建立問題回報時發送—— 可能是使用者從控制台提出（source: "user"），或由通話評分自動建立（source: "system"）。非阻塞。

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

欄位	類型	說明
`issue_report.severity`	string	`critical`、`warning` 或 `info`
`issue_report.status`	string	`open` 或 `resolved`
`issue_report.source`	string	`user`（從控制台提出）或 `system`（由評分建立）

重新評分通話會重建其系統產生的問題回報，並為重新建立的回報再次發出 issue.reported。若你只想針對每個根本問題收到一則通知，請依 call_id + title 去除重複項目。

測試通話事件

`test-call.completed`

當測試通話執行到達終止狀態時發送——completed 或 failed，包括在啟動時失敗且從未建立通話的執行。非阻塞。適合將批次 CI 執行串接至你的聊天／通知系統。

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

欄位	類型	說明
`test_call_run.target_type`	string	`agent` 或 `phone_number`
`test_call_run.target_id`	integer	執行目標的智慧體 ID 或電話號碼 ID，與 `target_type` 對應
`test_call_run.status`	string	`completed` 或 `failed`
`test_call_run.call_id`	integer \| null	若執行在撥出通話前失敗，則為 `null`
`test_call_run.error_message`	string	成功時為空白

警示事件

`alert.triggered`

當已啟用 傳送至開發人員 Webhook 管道的警示規則跨越其閾值時傳送。非阻塞。規則只會觸發一次，之後會遵守其冷卻時間，因此持續違規時，每個冷卻時間窗只會產生一個事件。

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

欄位	類型	說明
`event_id`（位於 `data`）	UUID	警示觸發 ID——與封裝層傳送用的 `event_id` 不同
`rule_id`, `rule_name`	UUID、字串	已觸發的規則
`metric`	字串	`success_rate`、`failure_rate`、`avg_score`、`call_volume` 或 `suite_regression`
`comparator`	字串	`lt`、`lte`、`gt` 或 `gte`
`metric_value`	數字	規則觸發時，指標在該時間窗內的值
`threshold`	數字	設定的閾值
`window_hours`	整數	回溯評估時間窗
`fired_at`	時間戳記

如要建立規則、設定指標與冷卻時間，以及使用電子郵件／Slack 管道，請參閱警示指南。

telephony.incoming / web.incoming

你必須回應的阻塞式來電酬載。

telephony.complete / web.complete

通話後的逐字稿與指標。

Webhook 端點

訂閱 URL 以接收這些事件中的部分事件。

函式工具

telephony.tool／web.tool 事件的產生方式。

Webhooks

Function Tools

通話事件

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

語音事件

`voice.ready`

`voice.failed`

品質事件

`call.graded`

`issue.reported`

測試通話事件

`test-call.completed`

警示事件

`alert.triggered`

相關內容

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook 端點

函式工具

​通話事件

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​語音事件

​voice.ready

​voice.failed

​品質事件

​call.graded

​issue.reported

​測試通話事件

​test-call.completed

​警示事件

​alert.triggered

​相關內容

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook 端點

函式工具

通話事件

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

語音事件

`voice.ready`

`voice.failed`

品質事件

`call.graded`

`issue.reported`

測試通話事件

`test-call.completed`

警示事件

`alert.triggered`

相關內容