--- title: "telephony.complete / web.complete" description: "通话结束时发送的非阻塞 Webhook，包含转录文本、录音 URL 和指标。" --- 每次通话结束后都会触发完成事件——包括呼入电话、 呼出电话、网页通话或测试通话（构建器麦克风会话）。该事件为 **非阻塞**：请返回任意 2xx 响应。 事件会通过以下两种路径发送： * **[Webhook 端点](/zh/webhooks/endpoints)**会接收 `telephony.complete`（电话通话）或 `web.complete`（网页通话和 构建器麦克风测试通话），其中包含下文所述的稳定载荷、 每次投递对应的 `event_id`、30 秒超时，以及 [最长 24 小时的重试机制](/zh/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` | 整数 | 在该通话的每个事件中保持稳定 | | `agent_id` | 整数 \| null | 处理该通话的智能体（如已分配） | | `agent_name` | 字符串 \| null | 处理该通话的智能体（如已分配） | | `direction` | 字符串 | `inbound`、`outbound`、`web`、`test`。历史载荷可能包含旧版 `mic` 或 `widget` 值 | | `from_number`, `to_number` | 字符串 | E.164。对于网页通话和测试通话，`from_number` 的字面值为 `"web"` | | `origin_domain` | 字符串 | **仅限网页/测试**——托管小组件的页面源（对于 mic 会话为空） | | `start_time`, `end_time` | 时间戳 | ISO 8601 UTC | | `duration_seconds` | 整数 \| null | 根据开始/结束时间得出 | | `status` | 字符串 | `completed` 或 `failed` | | `end_reason` | 字符串 | 见下表 | | `product`, `voice` | 字符串 | 通话时生效的智能体配置 | | `variables` | 对象 | 通话开始时快照保存的输入变量 | | `unresolved_variables` | 数组 | 通话配置中引用但在通话开始时未提供的变量名称 | | `transfer_number` | 字符串 \| null | 通话被转接时设置 | | `recording_url` | 字符串 \| null | 会过期的签名 URL；请及时下载。没有可用录音文件时为 `null` | | `recording_stopped_at` | 时间戳 \| null | 录音在通话结束前停止的时间；此时刻之后的内容不会包含在录音中。录音持续至通话结束或通话未录音时为 `null` | | `recording_stopped_reason` | 字符串 \| null | 录音提前停止的原因。`warm_transfer`：在[暖转接](/zh/guides/call-transfers)呼叫目标号码前立即停止录音，即使转接失败且来电者返回智能体，录音仍保持关闭。其他值仅供参考；未来可能会添加更多值。当 `recording_stopped_at` 为 `null` 时为 `null` | | `billable_minutes` | 数字 | 计费分钟数，四舍五入至最接近的四分之一分钟（以 15 秒为增量，最少 0.25 分钟）。直接转入语音信箱的通话仍会在此报告其实际计量分钟数，但费用按套餐费率最多计为一分钟。 | | `billing_total_cents` | 整数 | 美元分 | | `transcripts` | 数组 | 按轮次记录的转写条目；转写不可用时可以为空 | | `summary` | 字符串 \| null | 当智能体构建器中 **要收集的数据** 下的 **生成通话摘要** 已开启（[智能体](/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` | 对象 \| null | 结构化提取结果，包含 `status`、`fields`、`evidence`、`verification`、`field_reasons` 和 `schema_version`。每个非空字段都包含经过精确结构检查的引用文本（最多 1,000 个字符），以及其发言者角色和轮次索引；模型返回的较长引用会被拒绝，而不会被截断。字段为 `null` 时，证据为 `null`。`verified` 表示每个候选项恰好收到一条有效的独立判定。`unavailable` 也涵盖格式错误或不完整的验证器输出；有效的部分判定仍会生效，而没有一条有效判定的候选项会被置空。`status` 可以是 `completed`、`failed`、`exhausted`、`skipped` 或 `skipped_recording_disabled`；智能体没有提取字段时为 `null` | | `steps_trace` | 数组 | 仅适用于其智能体具有步骤或交接的通话。记录通话经过这些步骤的顺序：每个条目包含 `t_ms`（自通话开始以来的毫秒数）、`agent`（智能体的键，即 `a` 加其 ID）、`step`（步骤 ID；若交接至没有步骤的智能体则为 `null`）和 `via`（`start`、`model`、`condition`、`on_enter` 或 `handoff`）。仅包含 ID 和时间，因此即使关闭录音也会保留 | | `collected_values` | 对象 | 仅适用于其智能体具有步骤或交接的通话。智能体在其步骤中收集的值，以收集字段名称为键；另外还包含每个步骤 `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/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` | string | `user`、`model`、`tool` 或 `system` | | `content_type` | string | 语音使用 `text/plain`；工具调用、工具结果和系统事件使用 `application/json` | | `content` | string \| object | 语音文本，或上方所示的结构化对象。工具调用：`{"tool_call": name, "arguments": {…}}`。工具结果：`{"tool_name": name, "response": {…}}` | | `start_ms`, `end_ms` | integer | 相对于通话开始的偏移量，单位为毫秒。已知音频时间时提供 | | `ttfa_ms` | integer | 测量到时，`model` 轮次的首段音频响应时间 | | `audio_url`, `audio_urls` | string / array | 按轮次录制音频时，该轮次音频的会过期签名 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`（轮次架构与上方相同）。 * 字段集为原始的通话结束报告，可能包含超出上表范围的其他内部字段——请将未知字段视为参考信息。 * Web 通话（`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 访问相同数据，用于回填或重放。