事件目录

每个 webhook 正文都包含一个 type 字段，其值为本页面列出的事件类型之一。当您订阅某个端点时，events 数组必须包含您需要的事件类型（或留空以订阅所有事件）。这些事件通过两种投递方式传送：

端点投递始终是带有重试机制的非阻塞通知：请返回任意 2xx；信封中包含用于去重的 event_id。
阻塞式交互仅在旧版单 URL webhook上运行：包括 telephony.incoming / web.incoming 配置请求（webhook 模式号码和小部件密钥，10 秒超时），以及 webhook 模式的工具调度。您的响应将影响实时通话。

以下示例负载按在线传输顺序展示端点信封（键按字母顺序排序：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>"}。

`web.incoming`

telephony.incoming 的 Web 渠道对应事件，在Web 小组件会话或构建器麦克风测试通话开始时发送。端点投递针对每个 Web 会话均为即发即忘。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 的 Web 渠道对应事件，涵盖 Web 小组件通话（direction: "web"）和构建器麦克风测试通话（direction: "test"）。非阻塞。其载荷结构与 telephony.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 评分运行完成时发送。非阻塞。

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

在创建问题报告时发送——可以由用户通过控制台提交（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.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`

在测试通话运行达到终止状态时发送——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_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 渠道的告警规则达到其阈值时发送。不会阻塞。规则触发一次后会遵守其冷却时间，因此持续超限时，每个冷却窗口只会产生一个事件。

{
  "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 渠道的信息，请参阅告警指南。

telephony.incoming / web.incoming

您必须响应的阻塞式入站通话负载。

telephony.complete / web.complete

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

Webhook 端点

将 URL 订阅到这些事件中的一部分。

函数工具

telephony.tool / web.tool 事件的生成方式。

Webhooks

Function Tools

通话事件

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

质量事件

`call.graded`

`issue.reported`

测试通话事件

`test-call.completed`

告警事件

`alert.triggered`

相关内容

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook 端点

函数工具

​通话事件

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​质量事件

​call.graded

​issue.reported

​测试通话事件

​test-call.completed

​告警事件

​alert.triggered

​相关内容

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook 端点

函数工具

通话事件

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

质量事件

`call.graded`

`issue.reported`

测试通话事件

`test-call.completed`

告警事件

`alert.triggered`

相关内容