telephony.complete / web.complete

通话结束时发送的非阻塞 Webhook，包含转录文本、录音 URL 和指标。

每次通话结束后都会触发完成事件——包括呼入电话、呼出电话、网页通话或测试通话（构建器麦克风会话）。该事件为 非阻塞：请返回任意 2xx 响应。

事件会通过以下两种路径发送：

**Webhook 端点**会接收 telephony.complete（电话通话）或 web.complete（网页通话和构建器麦克风测试通话），其中包含下文所述的稳定载荷、每次投递对应的 event_id、30 秒超时，以及最长 24 小时的重试机制。
旧版单 URL Webhook 会进行一次同步尝试（10 秒超时，无重试），其载荷略有不同——请参阅旧版载荷差异。

请求负载（端点投递）

{
  "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`：在暖转接呼叫目标号码前立即停止录音，即使转接失败且来电者返回智能体，录音仍保持关闭。其他值仅供参考；未来可能会添加更多值。当 `recording_stopped_at` 为 `null` 时为 `null`
`billable_minutes`	数字	计费分钟数，四舍五入至最接近的四分之一分钟（以 15 秒为增量，最少 0.25 分钟）。直接转入语音信箱的通话仍会在此报告其实际计量分钟数，但费用按套餐费率最多计为一分钟。
`billing_total_cents`	整数	美元分
`transcripts`	数组	按轮次记录的转写条目；转写不可用时可以为空
`summary`	字符串 \| null	当智能体构建器中要收集的数据下的生成通话摘要已开启（智能体上的 `call_summary_enabled`），且生成成功时，返回通话后的自然语言摘要（两到四句散文，最多 2,000 个字符，使用通话语言：默认为智能体的主要语言，除非通话覆盖了该语言）；其他情况为 `null`，包括通话过短无法摘要、没有转写的通话，以及关闭录音的智能体。摘要与提取在同一个通话后步骤中生成，因此在发送通话完成 webhook 前等待提取的数据设置（`extraction_blocks_completion`）决定此事件是否等待它：在等待模式下，摘要会在发送此事件前准备就绪（摘要本身在该步骤的 75 秒预算内最多可使用 30 秒）；当事件不等待时（`never`，或 `except_transfers` 下的转接），此字段为 `null`，且摘要不会在 `call.data_extracted` 中重新发送，因此请稍后从通话对象上的 `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` 结果对应的 `<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 未返回可用配置，因此通话在智能体应答前结束。`status` 为 `failed`，且该通话不计费
`unknown`	无法确定结束原因

转录格式

transcripts 中的每个条目代表一个对话轮次。角色包括 user（来电者语音）、model（智能体语音以及工具调用）、 tool（工具结果）和 system（通话事件，例如语言切换）。

[
  {
    "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。

旧版负载差异

旧版单 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 (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}

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 });
  },
);

常见用例

CRM 集成

将每次通话的转录文本和录音 URL 与您的客户记录一并保存。

分析

将转录文本流式传输至管道，用于主题建模、CSAT 信号提取或转接率监控。

质量审查

在 QA 工具中打开通话以供人工审查，或通过您自己的评估模型进行处理。

通知

在转接或失败时通知人工团队成员。

telephony.complete / web.complete

请求负载（端点投递）#

结束原因#

转录格式#

旧版负载差异#

示例处理程序#

常见用例#

相关内容#