---
title: "事件目錄"
description: "ThunderPhone 發出的所有 Webhook 事件類型。"
---

每個 webhook 本體都包含 `type` 欄位，其值為本頁列出的其中一種事件
類型。當你訂閱某個
[端點](/zh-Hant/webhooks/endpoints)時，`events` 陣列必須包含你想要的
事件類型（或留空以訂閱所有事件——
但每回合事件 [`telephony.turn`](#telephony-turn) /
[`web.turn`](#web-turn) 除外，這些事件只會傳送至明確指定它們的
端點）。

這些事件有兩種傳送方式：

* **端點傳遞**一律為具有[重試機制](/zh-Hant/webhooks/overview)的**非阻塞**通知：以任意 2xx 回應；封套會包含可用於去重的 `event_id`。
* **阻塞式**互動僅會在[舊版單一 URL webhook](/zh-Hant/webhooks/overview)上執行：[`telephony.incoming` / `web.incoming`](/zh-Hant/webhooks/call-incoming)設定請求（webhook 模式號碼：包含一次重試共 13 秒；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
{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

### `telephony.complete`

當來電或撥出電信通話結束時傳送。非阻塞式。包含逐字稿、可用時的錄音 URL，以及計費摘要。如需承載資料結構描述，請參閱
[`telephony.complete` / `web.complete`](/zh-Hant/webhooks/call-complete)。

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

### `telephony.tool`

電信通話呼叫[函式工具](/zh-Hant/tools/overview)後傳送。這是非阻塞式稽核通知——傳遞此事件時工具已經執行完畢；涵蓋你的自訂函式工具及內建的 `send_sms` 工具（不包含其他內建工具、知識庫、應用程式連線或 MCP 工具）。針對 `send_sms`，`arguments.to` 和 `arguments.body` 都會是 `[REDACTED]`。完成逐字稿也會遮蔽這些內容；請使用回應中的 `message_id`，從組織範圍的 SMS 資源擷取內容與收件者。

```json
{
  "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>"}`。

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

### `telephony.turn`

電信通話**進行中**傳送，每個包含語音內容的輪次發生時各傳送一次——包括智慧體的語音完成內容與來電者的轉錄輪次。你可透過一般 webhook 即時追蹤對話，而無須輪詢
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript)。
非阻塞式。

<Note>
  **需要明確訂閱。** 與其他所有事件類型不同，輪次事件絕不會透過空白的 `events` 陣列（訂閱全部）傳遞。端點只有在其 `events` 清單明確包含 `telephony.turn` / `web.turn` 時才會收到這些事件。
</Note>

```json
{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |
| `position` | integer | 輪次在通話紀錄中的索引——用於排序的穩定識別值 |
| `role` | string | `assistant`（智慧體語音）或 `user`（來電者語音） |
| `text` | string | 發出事件時所知的輪次逐字稿文字 |
| `entry_type` | string | 基礎紀錄項目類型：`completion`（智慧體），或 `user_turn` / `span`（來電者） |
| `start_ms`, `end_ms` | integer | 自通話開始起算的音訊位移量，單位為毫秒；僅在發出事件時已知播放時序時提供 |

<Note>
  傳遞採至少一次語意，輪次可能會**亂序**到達：以封套的 `event_id` 去除重複項目，並依 `position` 排序。來電者逐字稿在發出後仍可能進一步修正；通話結束後的 [`telephony.complete`](/zh-Hant/webhooks/call-complete) 逐字稿為準。只有語音輪次會發出事件——工具呼叫、耳語及其他內部項目絕不會出現在此串流中。
</Note>

### `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
{
  "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` 為空白。

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

### `web.complete`

`telephony.complete` 的網頁頻道對應事件，涵蓋網頁小工具通話（`direction: "web"`）及建置工具麥克風測試通話（`direction: "test"`）。非阻塞式。承載資料結構與
[`telephony.complete`](/zh-Hant/webhooks/call-complete) 相同，另加上 `origin_domain`，並將 `from_number` 設為 `"web"`。

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

<Note>
  在舊版單一 URL webhook 上，建置工具麥克風測試通話過去會回報為 `telephony.complete`——只有 `direction:
  "web"` 通話會在該處使用 `web.complete` 類型。端點系統會將網頁與測試通話都對應至 `web.*`。歷史承載資料可能包含舊版 `direction` 值 `widget` 或 `mic`。
</Note>

### `web.tool`

`telephony.tool` 的網頁頻道對應事件。`data` 會以 `origin_domain` 取代 `from_number` / `to_number`。

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

### `web.turn`

[`telephony.turn`](#telephony-turn) 的網頁頻道對應事件，涵蓋網頁小工具通話及建置工具麥克風測試通話。承載資料結構相同，但以 `origin_domain` 取代 `from_number` / `to_number`。如同 `telephony.turn`，它需要**明確訂閱**——絕不會透過空白的 `events` 陣列傳遞。

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體 |

### `call.transfer_completed`

每通電話傳送一次，包含[通話轉接](/zh-Hant/guides/call-transfers)的最終結果：冷轉接，或暖轉接中語音智慧體退出後留下的人員橋接。
此事件不會阻塞，且僅傳送至端點（絕不傳送至舊版單一 URL webhook）。它會在通話的 `telephony.complete` 之後送達：當電信業者接手通話或轉接失敗時；或者，當 ThunderPhone 橋接通話時，在橋接結束後送達。

```json
{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `call_id` | integer | 已轉接的通話 |
| `agent_id` | integer \| null | 指派語音智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 指派語音智慧體時，處理該通話的智慧體名稱 |
| `transfer_outcome` | string | `refer_accepted`：電信業者接手通話。`bridged`：ThunderPhone 自行維持來電者與目的地之間的連線，可能是因為電信業者拒絕冷轉接，或暖轉接的智慧體已退出。`bridge_unanswered`：電信業者拒絕冷轉接，且目的地未接聽 ThunderPhone 自行撥出的電話。`failed`：轉接未成功，通話已結束 |
| `destination` | string \| null | 通話轉接至的號碼 |
| `sip_status` | integer \| null | 電信業者拒絕冷轉接時的 SIP 狀態：`403`（例如不支援通話轉接的 Twilio 中繼）、`405` 或 `501`。若電信業者未拒絕，則為 `null` |
| `bridge_kind` | string \| null | 僅限 `bridged`：`cold_fallback`（ThunderPhone 連線的已遭拒冷轉接）或 `warm`（暖轉接中智慧體退出後的兩位人員） |
| `bridge_seconds` | integer \| null | 僅限 `bridged`：ThunderPhone 計費的橋接時間，單位為秒 |
| `bridge_total_cents` | integer \| null | 僅限 `bridged`：扣除任何免費通話額度後，橋接的美元美分費用；此費用與通話的 `billing_total_cents` 分開計費 |

相同的值也會出現在[通話物件](/api-reference/calls#call-object)中，欄位為 `transfer_outcome`、`transfer_destination`、`transfer_sip_status`、`transfer_bridge_kind`、`transfer_bridge_seconds` 與 `transfer_bridge_total_cents`。同一通電話的每次傳送皆使用相同的 `event_id`，因此重複回報不會產生第二個事件。

---

## 簡訊事件

簡訊事件描述透過組織已連接的 Twilio 或 Telnyx 帳戶傳送的訊息。訊息內容會省略，且 `to` 會被遮蔽。
需要其內容或收件人時，請從
[`GET /v1/sms/{message_id}`](/api-reference/sms#retrieve-a-message) 擷取組織範圍的訊息。

### `sms.sent`

當客戶的電信業者接受外送簡訊要求時傳送。這不是手機送達回條。

```json
{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}
```

### `sms.failed`

在電信業者永久拒絕、暫時性錯誤的重試次數已耗盡，或結果最終無法確認時傳送。`error_code` 是穩定的 ThunderPhone 代碼，`error_message` 會在可提供時說明客戶應採取的動作。`status: "unknown"` 表示電信業者可能已接受該簡訊；請在電信業者紀錄中核對，因為 ThunderPhone 不會自動重新傳送。

### `sms.received`

保留供內送簡訊支援使用。目前版本不會發出 `sms.received` 事件。內送電信業者 Webhook 設定及簽章驗證將另行推出。

---

## 語音事件

自訂語音建立為非同步作業。這些非阻塞事件可讓你在取得最終結果時採取動作，而無須輪詢[複製語音詳細資料端點](/api-reference/custom-voices#list-and-retrieve-clones)。

`voice.ready` 和 `voice.failed` 僅會傳送至設定 `events: []` 的組織全域端點。無法將其選為明確的事件篩選條件。

### `voice.ready`

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

```json
{
  "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
{
  "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 | 自訂語音公開識別碼 |
| `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 評分執行](/api-reference/calls#ai-call-grading)完成時傳送。非阻塞式。

```json
{
  "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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|------|
| `agent_id` | integer \| null | 處理通話的智慧體（如有指派） |
| `agent_name` | string \| null | 處理通話的智慧體（如有指派） |
| `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 | |
| `report` | object \| null | 面向客戶的[通話報告](/api-reference/calls#call-report)：結果標籤、需要注意的標記及原因、來電者、單行摘要、來電者體驗。在早期啟發式評分中，其值為 `null` 或 `pending` 報告，且欄位為預留值；完整評分的事件會包含已完成的報告 |

<Note>
  一通通話可評分超過一次——快速的啟發式評分通常會在錄音可用後，
  接著進行完整模型評分，也可以手動重新評分。每次完成的執行都會
  發送各自的 `call.graded` 事件；請以最新的 `graded_at` 為準。
</Note>

### `call.data_extracted`

每當結構化資料擷取成功完成時傳送，包括在 `telephony.complete` / `web.complete` 後延遲重試，或透過
[`POST /v1/calls/{call_id}/extract`](/api-reference/calls#run-data-extraction) 手動重新執行。
非阻塞式。

在阻塞式擷取模式中，完成事件通常最多等待 75 秒的擷取預算。若擷取工作程序
遺失，正式環境的收尾排程（每五分鐘一次）會在開始下一次擷取嘗試前，釋出
`blocking_deadline_at` 已逾期的完成事件。後續成功會以此事件另行傳送。

<Warning>
  擷取的值是模型對對話的詮釋。每個非 null 的值均包含其依據的引述、說話者角色及回合索引，
  另加上執行層級的驗證旗標。涉及金錢、身分或存取權限的決策前，請先驗證結果。
</Warning>

```json
{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 處理通話的智慧體（如有指派） |
| `agent_name` | string \| null | 處理通話的智慧體（如有指派） |
| `summary` | string \| null | 智慧體啟用 **產生通話摘要** 時的已完成[通話摘要](/zh-Hant/webhooks/call-complete)，因此延遲的擷取事件也會傳送未能趕上完成時間窗的摘要；否則為 `null`。有摘要但沒有擷取欄位的智慧體不會發送此事件：請從 `GET /v1/calls/{call_id}` 讀取延遲摘要 |
| `extracted_data.status` | string | 此事件一律為 `completed` |
| `extracted_data.fields` | object | 以設定的擷取欄位鍵為索引的值；無法取得的值為 `null` |
| `extracted_data.evidence` | object | 以擷取欄位為索引的證據。非 null 值包含完全經結構檢查的引述（最多 1,000 個字元）、`speaker_role`（`caller` 或 `agent`）及 `turn_index`；模型傳回的較長引述會遭拒絕而非截斷，且其欄位為 `null` 時，證據一律為 `null` |
| `extracted_data.verification` | string | 僅當獨立證據檢查為每個候選欄位恰好傳回一個有效判定時，才為 `verified`。`unavailable` 表示檢查失敗、逾時、預算不足，或傳回格式錯誤或不完整的輸出。完全無法使用的檢查會保留具有結構依據的值供客戶審查。若為部分輸出，會套用有效判定，且每個沒有恰好一個有效判定的候選項目都會設為 null |
| `extracted_data.field_reasons` | object | 因結構依據或獨立驗證器而設為 null 的欄位之原因，以欄位為索引 |
| `extracted_data.schema_version` | string | 此次擷取所用確切欄位結構描述的雜湊值 |
| `extracted_at` | timestamp | ISO 8601 完成時間 |
| `model` | string | 用於擷取的模型 |

### `campaign.completed`

行銷活動從 `running` 轉為 `completed` 時傳送一次，不論是排程結束，
或所有聯絡人皆已進入終止狀態。執行器重試不會再次發送事件。此組織層級的
生命週期事件僅傳送至組織範圍端點，不會傳送至智慧體範圍端點。非阻塞式。

```json
{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}
```

四種結果計數彼此互斥，且合計為 `contacts_total`：
`completed` 包含成功聯絡的對象；`no_answer` 包含最終結果為未接聽的終止失敗／重試耗盡對象；
`failed` 包含所有其他終止失敗／重試耗盡對象；`remaining` 包含待處理、已排程或目前正在撥打的對象。
等待重試的聯絡人屬於 `remaining`，即使最近一次嘗試結果為未接聽亦然。僅發送一次的完成快照前，
會先協調處理進行中的通話。`started_at` 為設定的行銷活動開始時間；如未設定開始時間，則為行銷活動建立時間。

### `issue.reported`

建立[問題回報](/api-reference/issue-reports)時傳送——
可能是使用者從控制台提交（`source: "user"`），或由通話評分自動建立
（`source: "system"`）。非阻塞式。

```json
{
  "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"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 處理通話的智慧體（如有指派） |
| `agent_name` | string \| null | 處理通話的智慧體（如有指派） |
| `issue_report.severity` | string | `critical`、`warning` 或 `info` |
| `issue_report.status` | string | `open` 或 `resolved` |
| `issue_report.source` | string | `user`（從控制台提交）或 `system`（由評分建立） |

<Note>
  重新評分通話會重建其系統產生的問題回報，並針對重新建立的回報
  再次發送 `issue.reported`。若每個根本問題只需要一則通知，
  請以 `call_id` + `title` 去除重複項目。
</Note>

### `issue.escalated`

問題模式送交 ThunderPhone 供人員審查時傳送：在使用 **回報給 ThunderPhone** 後，
或「使用 AI 修正」無法確認客戶端修正並自動轉送問題時。只有組織範圍端點會接收此事件。

```json
{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `automatic` | boolean | 自動升級時為 `true`；手動升級時為 `false` |
| `cluster_id` | UUID | 已升級的問題模式 |
| `escalation_id` | UUID | 升級紀錄 |
| `status` | string | 事件發送時為 `open` |

這是通知，不是證據套件。使用 `cluster_id` 將其與問題模式建立關聯。
請參閱[回報給 ThunderPhone](/zh-Hant/guides/issues)。

---

## 測試通話事件

### `test-call.completed`

當
[測試通話執行](/api-reference/test-calls#test-call-run-object)
到達終止狀態——`completed` 或 `failed`——時傳送，包括在啟動時失敗且從未產生通話的執行。非阻塞式。適合將批次 CI 執行串接至你的聊天／通知系統。

```json
{
  "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"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `agent_id` | integer \| null | 已指派智慧體時，處理該通話的智慧體 |
| `agent_name` | string \| null | 已指派智慧體時，處理該通話的智慧體名稱 |
| `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
{
  "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 | 警示的**觸發識別碼**——與外層封裝的傳送 `event_id` 不同 |
| `rule_id`、`rule_name` | UUID、string | 已觸發的規則 |
| `metric` | string | `success_rate`、`failure_rate`、`avg_score`、`call_volume` 或 `suite_regression` |
| `comparator` | string | `lt`、`lte`、`gt` 或 `gte` |
| `metric_value` | number | 規則觸發時，該指標在視窗期間的值 |
| `threshold` | number | 設定的閾值 |
| `window_hours` | integer | 回溯評估視窗 |
| `fired_at` | timestamp | |

請參閱[警示指南](/zh-Hant/guides/alerts)，瞭解如何建立規則、指標、冷卻時間，以及電子郵件／Slack 管道。

---

## 遷移事件

### `migration.call.complete`

當透過
[`POST /v1/migrations/{id}/calls`](/api-reference/migration-calls) 發起的通話結束時傳送，
無論由哪個平台接聽。非阻塞式。事件最晚會在通話結束後約 5 分鐘內送達。`data` 包含
[`telephony.complete`](/zh-Hant/webhooks/call-complete) 的所有欄位，以及一個 `migration` 區塊。
ThunderPhone 發起的通話也會如常傳送 `telephony.complete`，且使用相同的 `call_id`。若其他平台上的通話在 2
小時後仍未結束，或其遷移已完成或先遺失金鑰，則會以
`status: "unknown"` 傳送，且不含逐字稿。

```json
{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `migration.id` | UUID | 遷移作業 |
| `migration.routing_id` | UUID | 已路由的通話，會在你發起通話時回傳 |
| `migration.arm` | string | `ours`（由 ThunderPhone 發起）或 `vendor`（由其他平台發起） |
| `migration.vendor` | string | `retell`、`vapi`、`elevenlabs` 或 `bland` |
| `migration.vendor_call_id` | string \| null | 其他平台的通話 id；`ours` 時為 `null` |
| `migration.metadata` | object | 你在發起通話時傳送的 `metadata` |
| `migration.vendor_cost_usd` | string \| null | 其他平台回報的通話費用（如有回報） |
| `call_id` | integer \| null | ThunderPhone 通話 id；`vendor` 時為 `null` |
| `status` | string | 對於 `vendor`：被叫方有接聽時為 `completed`，未接聽時為 `failed`，上述情況則為 `unknown`。對於 `ours`：與 `telephony.complete` 相同 |

對於 `vendor` 通話，ThunderPhone 不會提供計費或擷取資料：
`billable_minutes`、`billing_total_cents` 和 `extracted_data` 為 `null`，
`product` 和 `voice` 為空值，`recording_mode` 為 `vendor`，而
`recording_url` 則是其他平台提供的連結（如有）。

### `migration.rollback`

當遷移的漸進式切換自動將所有通話切回另一個平台時傳送：15
分鐘內有 3 通通話未能連線至 ThunderPhone、傳送至 ThunderPhone 的 2 通通話在智慧體接聽前結束，或
ThunderPhone 的任務結果率低於另一個平台的幅度超過設定的差距。非阻塞，每次復原傳送一次。之後，ThunderPhone 的
通話占比為 0%，遷移會暫停，直到有人在智慧體的「遷移」分頁中恢復。承載資料不含電話號碼、逐字稿或
通話 ID。

```json
{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}
```

| 欄位 | 類型 | 說明 |
|-------|------|-------------|
| `migration_id` | UUID | 遷移 |
| `vendor` | string | `retell`、`vapi`、`elevenlabs` 或 `bland` |
| `reason` | string | `ours_failed_burst`（15 分鐘內有 3 次連線失敗）、`dropped_calls`（30 分鐘內有 2 通通話在智慧體接聽前結束），或 `rate_gap`（雙方各至少有 `rollback_min_calls` 通已評分通話時的任務結果率差距） |
| `previous_percent` | integer | 復原前 ThunderPhone 的通話占比 |
| `ours_percent` | integer | 一律為 `0` |
| `step` | integer \| null | 當時所在的排程步驟（以 0 為起點） |
| `ours` / `theirs` | object \| null | 目前步驟中已評分的通話及其成功率；當該步驟的通話數不足時，`theirs` 可能為最近 30 天的資料。沒有資料時為 `null` |
| `ours_failed` | integer | 最近 15 分鐘內計入的連線失敗次數 |
| `dropped` | integer | 最近 30 分鐘內計入為中斷的通話數 |
| `rolled_back_at` | timestamp | |

---

## 相關內容

<CardGroup cols={2}>
  <Card title="telephony.incoming / web.incoming" icon="phone" href="/zh-Hant/webhooks/call-incoming">
    你必須回應的阻塞式撥入通話負載。
  </Card>
  <Card title="telephony.complete / web.complete" icon="phone-slash" href="/zh-Hant/webhooks/call-complete">
    通話後逐字稿與指標。
  </Card>
  <Card title="Webhook 端點" icon="bolt" href="/zh-Hant/webhooks/endpoints">
    訂閱 URL 以接收這些事件的子集。
  </Card>
  <Card title="函式工具" icon="screwdriver-wrench" href="/zh-Hant/tools/overview">
    `telephony.tool`／`web.tool` 事件的產生方式。
  </Card>
</CardGroup>