ThunderPhone 2.0 正式上线。全程自助，2 美分/分钟起。查看发布公告
立即开始

Webhooks

事件目录

ThunderPhone 发出的所有 webhook 事件类型。

每个 Webhook 正文都包含一个 type 字段，其值为本页中的某一种事件 类型。当您订阅某个 端点时，events 数组必须包含您需要的 事件类型（或留空以订阅所有事件—— 但每轮事件 telephony.turn / web.turn 除外，这些事件仅会发送到明确 指定它们的端点）。

这些事件通过两种交付方式传递：

以下示例载荷按传输顺序展示端点信封 （键按字母顺序排序：data、event_id、type）；旧版交付包含相同的 data，但不含 event_id。

通话事件

telephony.incoming

当入站呼叫到达您的某个电话号码时发送。端点投递是针对每个入站呼叫发送的即发即弃通知，无论该号码配置的是智能体还是 webhook。未分配智能体的号码还会通过旧版 webhook 接收阻塞式配置请求——完整的请求／响应架构请参阅 telephony.incoming / web.incoming。

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

telephony.tool

电话呼叫调用函数工具后发送。非阻塞审计通知——投递此事件时，工具已执行完毕；它涵盖您自己的函数工具（不包括内置工具、知识库工具、应用连接工具或 MCP 工具）。

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

telephony.turn

在电话呼叫进行中发送，每个包含语音的轮次发生时发送一次——包括智能体的口语回复以及来电者的转录轮次。您可以通过普通 webhook 跟踪实时对话，无需轮询 GET /v1/calls/{call_id}/transcript。非阻塞。

{
  "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"
}
字段类型说明
positioninteger该轮次在通话记录中的索引——用于排序的稳定标识
rolestringassistant（智能体语音）或 user（来电者语音）
textstring发送时已知的该轮次转录文本
entry_typestring底层通话记录条目类型：completion（智能体），或 user_turn / span（来电者）
start_ms, end_msinteger自通话开始起的音频偏移量，单位为毫秒；仅当发送时已知播放时序才会提供

web.incoming

telephony.incoming 的网页渠道等效事件，在网页小组件会话或构建器麦克风测试呼叫开始时发送。端点投递是针对每个网页会话的即发即弃通知。处于 mode="webhook" 的可发布密钥还会通过旧版 webhook 接收阻塞式配置请求——该阻塞请求具有不同的结构（origin_domain、publishable_key_prefix；没有电话号码）。请参阅 telephony.incoming / web.incoming。

{
  "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 相同，并额外包含 origin_domain，其中 from_number 设置为 "web"。

web.tool

telephony.tool 的网页渠道等效事件。data 使用 origin_domain 代替 from_number / to_number。

web.turn

telephony.turn 的网页渠道等效事件，涵盖网页小组件呼叫和构建器麦克风测试呼叫。负载结构相同，但使用 origin_domain 代替 from_number / to_number。与 telephony.turn 一样，它需要显式订阅——绝不会通过空的 events 数组投递。

语音事件

自定义语音创建为异步操作。这些非阻塞事件让您能够在获得最终结果后作出响应，而无需轮询克隆详情端点。

voice.ready

在自定义语音完成处理并可分配给智能体时发送。

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

在自定义语音处理发生永久性失败时发送。

{
  "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.idstring自定义语音公开 ID
voice.namestring智能体语音值，格式为 custom:<public_id>
voice.display_namestring面向组织显示的语音名称
voice.languagestring克隆语音的单一语言代码
voice.genderstringmale、female 或空字符串
voice.statusstring对于 voice.ready 为 ready；对于 voice.failed 为 failed
voice.failure_reasonstring成功时为空；失败时为处理失败详情
voice.created_at, voice.updated_attimestampISO 8601 时间戳
reasonstring失败详情；仅在 voice.failed 中存在

质量事件

call.graded

当某个通话的 AI 评分运行 完成时发送。非阻塞。

{
  "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.idinteger评分 ID
grade.scoreinteger | null0–100
grade.call_outcomestringsuccess、failure、unknown 或 no_conversation
grade.summarystring单段摘要
grade.detected_issuesarray评分器发现的问题字符串
grade.statusstring始终为 completed——仅已完成的运行会发送
grade.grader_modelstring生成结果的评分器（例如 heuristic-v1）
grade.graded_at, grade.created_attimestamp

issue.reported

当创建问题报告时发送——可以是用户从控制台提交的报告（source: "user"），也可以是通话评分自动创建的报告（source: "system"）。非阻塞。

{
  "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.severitystringcritical、warning 或 info
issue_report.statusstringopen 或 resolved
issue_report.sourcestringuser（从控制台提交）或 system（由评分创建）

测试通话事件

test-call.completed

当测试通话运行 达到终止状态时发送——completed 或 failed，包括启动时失败且从未生成通话的运行。非阻塞。适合将批量 CI 运行接入您的聊天或通知系统。

{
  "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_typestringagent 或 phone_number
test_call_run.target_idinteger运行所针对的智能体 ID 或电话号码 ID，与 target_type 对应
test_call_run.statusstringcompleted 或 failed
test_call_run.call_idinteger | null运行在发起通话前失败时为 null
test_call_run.error_messagestring成功时为空

告警事件

alert.triggered

当启用了 发送到开发者 Webhook 渠道的告警规则达到其阈值时发送。 非阻塞。规则触发一次后会遵循其冷却时间，因此持续超限时，每个冷却窗口只会产生一个事件。

{
  "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_nameUUID、字符串已触发的规则
metric字符串success_rate、failure_rate、avg_score、call_volume 或 suite_regression
comparator字符串lt、lte、gt 或 gte
metric_value数值规则触发时，该指标在窗口内的值
threshold数值配置的阈值
window_hours整数滚动评估窗口
fired_at时间戳

有关创建规则、指标、冷却时间以及电子邮件 / Slack 渠道的信息，请参阅告警指南。

相关内容

telephony.incoming / web.incoming

您必须响应的阻塞式入站来电负载。

telephony.complete / web.complete

通话后的转写文本和指标。

Webhook 端点

将 URL 订阅至这些事件的一个子集。

函数工具

如何生成 telephony.tool / web.tool 事件。