--- title: "telephony.complete / web.complete" description: "通話結束時傳送的非阻塞 Webhook，包含逐字稿、錄音 URL 和指標。" --- 每次通話結束後都會觸發完成事件——包括來電電話、撥出電話、網路通話或測試通話（建構工具麥克風工作階段）。此事件為**非阻塞式**：請以任意 2xx 回應。 事件會透過兩種路徑傳送： * **[Webhook 端點](/zh-Hant/webhooks/endpoints)**會收到 `telephony.complete`（電話通話）或 `web.complete`（網路通話和建構工具麥克風測試通話），其中包含下方說明的穩定承載資料、每次傳送專屬的 `event_id`、30 秒逾時，以及[最長 24 小時的重試機制](/zh-Hant/webhooks/overview)。 * **[舊版單一 URL webhook](/api-reference/organizations#legacy-single-url-webhook)**會收到一次同步嘗試（10 秒逾時，不重試），其承載資料略有不同——請參閱[舊版承載資料差異](#legacy-payload-differences)。 ## 請求酬載（端點傳送） ```json { "data": { "billable_minutes": 1.25, "billing_total_cents": 8, "call_id": 987654321, "direction": "inbound", "duration_seconds": 54, "end_reason": "user_hangup", "end_time": "2026-04-20T18:25:04.822Z", "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..." }, "from_number": "+14155550199", "product": "spark", "recording_stopped_at": null, "recording_stopped_reason": null, "recording_url": "https://storage.example.com/…", "start_time": "2026-04-20T18:24:10.113Z", "status": "completed", "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23. The agent read the appointment back and Alex asked for a reminder text the day before.", "to_number": "+15551234567", "transcripts": [ /* see Transcript format */ ], "transfer_number": null, "unresolved_variables": ["campaign_owner"], "variables": {"campaign_name": "Spring renewals"}, "voice": "john" }, "event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d", "type": "telephony.complete" } ``` | 欄位 | 類型 | 說明 | |-------|------|-------------| | `call_id` | integer | 此通話在所有事件中均保持不變 | | `agent_id` | integer \| null | 處理通話的智慧體（如有指派） | | `agent_name` | string \| null | 處理通話的智慧體（如有指派） | | `direction` | string | `inbound`、`outbound`、`web`、`test`。歷史承載資料可能包含舊版的 `mic` 或 `widget` 值 | | `from_number`, `to_number` | string | E.164。網頁通話和測試通話的 `from_number` 為字面值 `"web"` | | `origin_domain` | string | **僅限 Web/test**——承載小工具的頁面來源網域（mic 工作階段為空） | | `start_time`, `end_time` | timestamp | ISO 8601 UTC | | `duration_seconds` | integer \| null | 根據開始／結束時間推導 | | `status` | string | `completed` 或 `failed` | | `end_reason` | string | 請參閱下表 | | `product`, `voice` | string | 通話當下生效的智慧體設定 | | `variables` | object | 通話開始時建立快照的輸入變數 | | `unresolved_variables` | array | 通話設定中引用但在通話開始時未提供的變數名稱 | | `transfer_number` | string \| null | 通話轉接時設定 | | `recording_url` | string \| null | 有效期限有限的已簽署 URL；請儘速下載。沒有可用錄音檔案時為 `null` | | `recording_stopped_at` | timestamp \| null | 錄音在通話結束前停止的時間；錄音不會包含此時刻之後的內容。錄音持續至通話結束，或通話未錄音時為 `null` | | `recording_stopped_reason` | string \| null | 錄音提前停止的原因。`warm_transfer`：在[暖轉接](/zh-Hant/guides/call-transfers)呼叫目的地之前，錄音會立即停止；即使轉接失敗且來電者回到智慧體，錄音仍會保持關閉。其他值僅供參考；未來可能新增更多值。當 `recording_stopped_at` 為 `null` 時為 `null` | | `billable_minutes` | number | 計費分鐘數，四捨五入至最接近的四分之一分鐘（每 15 秒遞增，最低 0.25）。直接轉入語音信箱的通話仍會在此回報實際計量分鐘數，但費用會依方案費率上限為一分鐘。 | | `billing_total_cents` | integer | 美元美分 | | `transcripts` | array | 每輪逐字稿項目；逐字稿無法取得時可為空 | | `summary` | string \| null | 當智慧體建置工具中的 **要收集的資料** 下已啟用 **產生通話摘要**（[Agent](/api-reference/agents) 上的 `call_summary_enabled`），且產生成功時，提供以自然語言撰寫的通話後摘要（兩到四句散文，最多 2,000 個字元，使用通話語言：預設為智慧體的主要語言，除非通話覆寫該設定）；否則為 `null`，包括通話過短而無法摘要、沒有逐字稿的通話，以及已關閉錄音的智慧體。摘要會在與擷取相同的通話後步驟中產生，因此 **在傳送通話完成 webhook 前等待擷取資料** 設定（`extraction_blocks_completion`）決定此事件是否等待摘要：在等待模式中，此事件送出前摘要已準備完成（摘要本身在該步驟 75 秒的預算中最多可使用 30 秒）；當事件不等待時（`never`，或 `except_transfers` 下的轉接），此欄位為 `null`，且摘要**不會**在 `call.data_extracted` 中再次傳送，因此請稍後從[通話物件](/api-reference/calls#call-object)的 `summary` 讀取。控制台的通話頁面也會顯示摘要 | | `extracted_data` | object \| null | 結構化擷取結果，包含 `status`、`fields`、`evidence`、`verification`、`field_reasons` 與 `schema_version`。每個非 null 欄位都包含經結構驗證的精確引文（最多 1,000 個字元），以及其發言者角色和輪次索引；模型回傳過長的引文會被拒絕，而非截斷。欄位為 `null` 時，證據為 `null`。`verified` 表示每個候選項目都恰好收到一個有效的獨立判定。`unavailable` 也涵蓋格式錯誤或不完整的驗證器輸出；有效的不完整判定仍會套用，而沒有任何有效判定的候選項目會設為 null。`status` 為 `completed`、`failed`、`exhausted`、`skipped` 或 `skipped_recording_disabled`；智慧體沒有擷取欄位時為 `null` | | `steps_trace` | array | 僅適用於智慧體具有步驟或交接的通話。通話經過這些項目的順序：每個項目包含 `t_ms`（自通話開始以來的毫秒數）、`agent`（智慧體的金鑰，即 `a` 加上其 ID）、`step`（步驟 ID，或交接至沒有步驟的智慧體時為 `null`）以及 `via`（`start`、`model`、`condition`、`on_enter` 或 `handoff`）。僅保留 ID 和時間，因此即使錄音已關閉也會保留 | | `collected_values` | object | 僅適用於智慧體具有步驟或交接的通話。智慧體在各步驟中收集的值，以收集欄位名稱為金鑰，另加上每個步驟 `on_enter_tool` 結果的 `_result`。通話內容未保留時（錄音已關閉）會省略 | ### 結束原因 | 值 | 意義 | |-------|---------| | `user_hangup` | 遠端通話方先掛斷電話 | | `ai_hangup` | AI 主動結束通話 | | `ai_transfer` | AI 轉接了通話；已設定 `transfer_number` | | `ai_warm_transfer` | AI 已完成暖轉接（有人接聽的轉接） | | `voicemail_hangup` | 偵測到語音信箱，並依照你的 `voicemail_action` 結束通話 | | `max_duration` | 通話達到最長時長限制：智慧體的限制、通話自身的限制，或平台的 6 小時限制。AI 或來電者在時長限制警告後結束的通話，會保留 `ai_hangup` 或 `user_hangup` | | `superseded` | 工作階段已被較新的工作階段取代 | | `inbound_config_webhook_failed` | webhook 模式號碼的來電：[設定 webhook](/zh-Hant/webhooks/call-incoming) 未回傳可用的設定，因此通話在智慧體接聽前即已結束。`status` 為 `failed`，且此通話不計費 | | `unknown` | 無法判定結束原因 | ## 對話紀錄格式 `transcripts` 中的每個項目代表一個對話輪次。角色包括 `user`（來電者語音）、`model`（智慧體語音 **以及** 工具呼叫）、 `tool`（工具結果）和 `system`（例如語言切換等通話事件）。 ```json [ { "role": "user", "content_type": "text/plain", "content": "Hi, I'm calling about my appointment.", "start_ms": 1200, "end_ms": 4100, "audio_url": "https://storage.example.com/…" }, { "role": "model", "content_type": "text/plain", "content": "Sure, what date works best?", "start_ms": 4200, "end_ms": 6100 }, { "role": "model", "content_type": "application/json", "content": { "tool_call": "search_appointments", "arguments": { "date": "2026-04-21" } } }, { "role": "tool", "content_type": "application/json", "content": { "tool_name": "search_appointments", "response": { "available_slots": ["9:00 AM", "2:00 PM"] } } } ] ``` | 欄位 | 類型 | 說明 | |-------|------|-------------| | `role` | 字串 | `user`、`model`、`tool` 或 `system` | | `content_type` | 字串 | 語音使用 `text/plain`；工具呼叫、工具結果和系統事件使用 `application/json` | | `content` | 字串 \| 物件 | 語音文字，或上述顯示的結構化物件。工具呼叫：`{"tool_call": name, "arguments": {…}}`。工具結果：`{"tool_name": name, "response": {…}}` | | `start_ms`、`end_ms` | 整數 | 相對於通話開始的位移，單位為毫秒。已知音訊時間時會提供 | | `ttfa_ms` | 整數 | 測得時 `model` 輪次的首次音訊時間 | | `audio_url`、`audio_urls` | 字串／陣列 | 依輪次錄音時，該輪次音訊的即將到期簽署 URL | 如需完整結構化的輪次歷程（包含中斷標記、 確認提示和原始位置），請使用 [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history)。 ## 舊版酬載差異 舊版單一 URL Webhook 封套為 `{"type": "telephony.complete" | "web.complete", "data": {…}}`，且 **不含 `event_id`**；其 `data` 與端點酬載不同： 舊版完成酬載也會包含 `agent_id` 和 `agent_name`。 * 輪次陣列位於 **`history`**，而非 `transcripts`（輪次結構與上方相同）。 * 欄位集合是原始的通話結束報告，可能包含超出上表的其他內部欄位——請將未知欄位視為參考資訊。 * 網頁通話（`direction: "web"`）**不包含** `from_number`／`to_number`，並會新增 `origin_domain`。 * Builder 麥克風測試通話會在舊版路徑上回報為 `telephony.complete`（端點系統會將其對應為 `web.complete`）。 * **轉接協調**：當通話在轉接期間結束時，舊版 Webhook 會同步呼叫，並可能回應 `{"transfer_ready": false}`，表示交接目標尚未準備完成。任何其他回應（或未設定舊版 Webhook）都會讓轉接繼續進行。端點傳送絕不會用於此用途。 --- ## 處理常式範例 ```python Python (FastAPI) import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, signature: str) -> bool: expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature or "") @app.post("/thunderphone-webhook") async def webhook(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(status_code=401) event = json.loads(body) if event["type"] in ("telephony.complete", "web.complete"): data = event["data"] # Endpoint deliveries use "transcripts"; the legacy webhook uses "history". turns = data.get("transcripts") or data.get("history") or [] await persist_call_record( call_id=data["call_id"], turns=turns, recording_url=data.get("recording_url"), ) if data["end_reason"] in ("ai_transfer", "ai_warm_transfer"): await notify_team(data.get("transfer_number"), data["call_id"]) return {"ok": True} ``` ```javascript Node.js (Express) import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, signature) { const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex"); return signature && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } app.post( "/thunderphone-webhook", express.raw({ type: "application/json" }), async (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); if (["telephony.complete", "web.complete"].includes(event.type)) { const data = event.data; // Endpoint deliveries use "transcripts"; the legacy webhook uses "history". const turns = data.transcripts ?? data.history ?? []; await persistCallRecord({ ...data, turns }); if (["ai_transfer", "ai_warm_transfer"].includes(data.end_reason)) { await notifyTeam(data.transfer_number, data.call_id); } } res.json({ ok: true }); }, ); ``` --- ## 常見使用案例 將每通電話的逐字稿和錄音 URL 與你的客戶紀錄一併保存。 將逐字稿串流至管線，用於主題建模、CSAT 訊號擷取或轉接率監控。 在 QA 工具中開啟通話供人工審查，或透過你自己的評估模型處理。 在轉接／失敗時通知團隊成員。 --- ## 相關內容 在通話開始時執行的同步對應事件。 你可以訂閱的其他事件類型。 可透過 REST 存取相同資料，以進行回填／重播。