> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # 事件目录 > ThunderPhone 发出的所有 Webhook 事件类型。 每个 webhook 正文都包含一个 `type` 字段，其值为本页面列出的事件类型之一。当您订阅某个[端点](/zh/webhooks/endpoints)时，`events` 数组必须包含您需要的事件类型（或留空以订阅所有事件）。 这些事件通过两种投递方式传送： * **端点投递**始终是带有[重试机制](/zh/webhooks/overview)的**非阻塞**通知：请返回任意 2xx；信封中包含用于去重的 `event_id`。 * **阻塞式**交互仅在[旧版单 URL webhook](/zh/webhooks/overview)上运行：包括 [`telephony.incoming` / `web.incoming`](/zh/webhooks/call-incoming) 配置请求（webhook 模式号码和小部件密钥，10 秒超时），以及 webhook 模式的[工具调度](/zh/tools/overview)。您的响应将影响实时通话。 以下示例负载按在线传输顺序展示端点信封（键按字母顺序排序：`data`、`event_id`、`type`）；旧版投递包含相同的 `data`，但不含 `event_id`。 ## 通话事件 ### `telephony.incoming` 当入站通话接入您的某个[电话号码](/api-reference/phone-numbers)时发送。端点投递是针对**每一通**入站通话发送的即发即忘通知，无论该号码配置的是智能体还是 webhook。未分配智能体的号码还会通过旧版 webhook 接收**阻塞式**配置请求——完整的请求／响应架构请参阅 [`telephony.incoming` / `web.incoming`](/zh/webhooks/call-incoming)。 ```json theme={null} { "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`](/zh/webhooks/call-complete)。 ### `telephony.tool` 电话通话调用[函数工具](/zh/tools/overview)后发送。非阻塞审计通知——投递此事件时，工具已经执行完毕；它涵盖您自己的函数工具（不包括内置工具、知识库工具、应用连接工具或 MCP 工具）。 ```json theme={null} { "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": , "response": }`，失败时为 `{"status": , "error": ""}`。 ### `web.incoming` `telephony.incoming` 的 Web 渠道对应事件，在[Web 小组件](/zh/widget/overview)会话或构建器麦克风测试通话开始时发送。端点投递针对每个 Web 会话均为即发即忘。`mode="webhook"` 中的可发布密钥还会通过旧版 webhook 接收**阻塞式**配置请求——该阻塞式请求的结构不同（`origin_domain`、`publishable_key_prefix`；不包含电话号码）。请参阅 [`telephony.incoming` / `web.incoming`](/zh/webhooks/call-incoming)。 ```json theme={null} { "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` 的 Web 渠道对应事件，涵盖 Web 小组件通话（`direction: "web"`）和构建器麦克风测试通话（`direction: "test"`）。非阻塞。其载荷结构与 [`telephony.complete`](/zh/webhooks/call-complete)相同，另加 `origin_domain`，且 `from_number` 设置为 `"web"`。 在旧版单 URL webhook 中，构建器麦克风测试通话历史上会报告为 `telephony.complete`——其中仅 `direction: "web"` 通话使用 `web.complete` 类型。端点系统会将 Web 通话和测试通话都映射为 `web.*`。历史载荷可能包含旧版 `direction` 值 `widget` 或 `mic`。 ### `web.tool` `telephony.tool` 的 Web 渠道对应事件。`data` 携带 `origin_domain`，而不是 `from_number` ／ `to_number`。 *** ## 质量事件 ### `call.graded` 在某通话的 [AI 评分运行](/api-reference/calls#ai-call-grading) 完成时发送。非阻塞。 ```json theme={null} { "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.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 | | 一通电话可以被评分多次——快速启发式评分通常会在录音可用后由完整模型评分跟进，也可以进行手动重新评分。每次完成的运行都会发送各自的 `call.graded` 事件；请以最新的 `graded_at` 为准。 ### `issue.reported` 在创建[问题报告](/api-reference/issue-reports)时发送——可以由用户通过控制台提交（`source: "user"`），也可以由通话评分自动创建（`source: "system"`）。非阻塞。 ```json theme={null} { "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.severity` | string | `critical`、`warning` 或 `info` | | `issue_report.status` | string | `open` 或 `resolved` | | `issue_report.source` | string | `user`（从控制台提交）或 `system`（由评分创建） | 对通话重新评分会重新构建其系统生成的问题报告，并会为重新创建的报告再次发送 `issue.reported`。如果您只想针对每个底层问题接收一条通知，请按 `call_id` + `title` 去重。 *** ## 测试通话事件 ### `test-call.completed` 在[测试通话运行](/api-reference/test-calls#test-call-run-object) 达到终止状态时发送——`completed` 或 `failed`，包括启动时失败且从未发起通话的运行。非阻塞。适用于将批量 CI 运行接入您的聊天／通知系统。 ```json theme={null} { "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_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/guides/alerts)达到其阈值时发送。 不会阻塞。规则触发一次后会遵守其冷却时间，因此持续超限时，每个冷却窗口只会产生一个事件。 ```json theme={null} { "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_name` | UUID、字符串 | 已触发的规则 | | `metric` | 字符串 | `success_rate`、`failure_rate`、`avg_score`、`call_volume` 或 `suite_regression` | | `comparator` | 字符串 | `lt`、`lte`、`gt` 或 `gte` | | `metric_value` | 数字 | 规则触发时指标在该窗口内的值 | | `threshold` | 数字 | 已配置的阈值 | | `window_hours` | 整数 | 滚动评估窗口 | | `fired_at` | 时间戳 | | 有关创建规则、指标、冷却时间以及电子邮件 / Slack 渠道的信息，请参阅[告警指南](/zh/guides/alerts)。 *** ## 相关内容 您必须响应的阻塞式入站通话负载。 通话后的转录文本和指标。 将 URL 订阅到这些事件中的一部分。 `telephony.tool` / `web.tool` 事件的生成方式。