> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # 事件目錄 > ThunderPhone 發出的所有 Webhook 事件類型。 每個 Webhook 主體都有一個 `type` 欄位，其值為本頁列出的其中一種事件 類型。當你訂閱某個 [端點](/zh-Hant/webhooks/endpoints)時，`events` 陣列必須包含你想要的 事件類型（或留空以訂閱所有事件）。 這些事件有兩種傳送方式： * **端點傳送**一律為具備[重試機制](/zh-Hant/webhooks/overview)的**非阻塞式** 通知：請回應任意 2xx；封裝內容含有可用於去重的 `event_id`。 * **阻塞式**交換僅會在 [舊版單一 URL Webhook](/zh-Hant/webhooks/overview)上執行：包括 [`telephony.incoming` / `web.incoming`](/zh-Hant/webhooks/call-incoming) 設定請求（Webhook 模式號碼與小工具金鑰，逾時時間為 10 秒），以及 Webhook 模式的 [工具派送](/zh-Hant/tools/overview)。你的回應會影響即時通話。 以下範例酬載會依傳輸順序顯示端點封裝內容 （鍵依字母順序排列：`data`、`event_id`、`type`）；舊版傳送包含相同的 `data`，但不含 `event_id`。 ## 通話事件 ### `telephony.incoming` 當來電通話抵達你的其中一個 [電話號碼](/api-reference/phone-numbers)時傳送。端點傳送是針對**每一通**來電通話的即發即忘通知，無論 該號碼是否已設定智慧體或 webhook。未指派智慧體的號碼還會在舊版 webhook 上收到**阻塞式** 設定請求——完整的請求／回應結構請參閱 [`telephony.incoming` / `web.incoming`](/zh-Hant/webhooks/call-incoming)。 ```json theme={null} { "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`](/zh-Hant/webhooks/call-complete)。 ### `telephony.tool` 電信通話呼叫 [函式工具](/zh-Hant/tools/overview)後傳送。非阻塞式稽核通知—— 傳送此事件時，工具已執行完成；此事件涵蓋 你自己的函式工具（不包括內建工具、知識庫工具、應用程式連線工具 或 MCP 工具）。 ```json theme={null} { "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": , "response": }`，失敗時為 `{"status": , "error": ""}`。 ### `web.incoming` `telephony.incoming` 的網頁頻道對應事件，當 [網頁小工具](/zh-Hant/widget/overview)工作階段或建置器麥克風測試通話 開始時傳送。端點傳送是針對每個網頁工作階段的即發即忘通知。 `mode="webhook"` 中的可發布金鑰還會在舊版 webhook 上收到 **阻塞式**設定請求——該阻塞式請求的格式不同（`origin_domain`、 `publishable_key_prefix`；沒有電話號碼）。請參閱 [`telephony.incoming` / `web.incoming`](/zh-Hant/webhooks/call-incoming)。 ```json theme={null} { "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`](/zh-Hant/webhooks/call-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`。 *** ## 語音事件 自訂語音建立為非同步作業。這些非阻塞事件可讓你在取得最終結果時做出回應，而無須輪詢[複製詳情端點](/api-reference/custom-voices#list-and-retrieve-clones)。 ### `voice.ready` 當自訂語音完成處理並可指派給智慧體時傳送。 ```json theme={null} { "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` 當自訂語音處理發生永久性失敗時傳送。 ```json theme={null} { "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:` 的智慧體語音值 | | `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 評分執行](/api-reference/calls#ai-call-grading) 完成時發送。非阻塞。 ```json theme={null} { "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` 建立[問題回報](/api-reference/issue-reports)時發送—— 可能是使用者從控制台提出（`source: "user"`），或由 通話評分自動建立（`source: "system"`）。非阻塞。 ```json theme={null} { "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` 當 [測試通話執行](/api-reference/test-calls#test-call-run-object) 到達終止狀態時發送——`completed` 或 `failed`，包括在啟動時 失敗且從未建立通話的執行。非阻塞。適合將批次 CI 執行串接至你的 聊天／通知系統。 ```json theme={null} { "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** 管道的[警示規則](/zh-Hant/guides/alerts)跨越其閾值時傳送。 非阻塞。規則只會觸發一次，之後會遵守其冷卻時間，因此持續違規時，每個冷卻時間窗只會產生一個事件。 ```json theme={null} { "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 管道，請參閱[警示指南](/zh-Hant/guides/alerts)。 *** ## 相關內容 你必須回應的阻塞式來電酬載。 通話後的逐字稿與指標。 訂閱 URL 以接收這些事件中的部分事件。 `telephony.tool`／`web.tool` 事件的產生方式。