Call API 与 Webhook 开发指南:密钥、权限与事件
Call REST API 实用导览:API 密钥与权限范围、速率限制、错误处理、带签名的 Webhook,以及用于管理端点的「开发者」页面。
电话系统迟早要与其他系统对接:CRM 需要在通话结束时显示该通话,计费工具想知道是谁来过电话,某个脚本要在表单提交时发起呼叫。Call 提供 REST API 和外发 Webhook,正是为此而设。本指南说明各部分如何组合、写代码之前要申请什么,以及最常让开发者白白浪费一个下午的错误。

如果你只是想批量迁移联系人,请先阅读向电话团队 CRM 导入联系人;导入往往比集成更简单。
从哪里开始:API 参考和「开发者」页面
有两个地方需要了解。「API 参考」位于「设置」下,也可以从首页的「资源」菜单进入。它无需登录即可阅读,在为客户评估工作量时非常方便。「开发者」页面同样位于「设置」下,面向你自己的工作区:它显示你的组织和智能体标识、你的 Webhook 端点,以及只读的密钥列表。
各处能提供什么
- 从这里开始基础 URL 与约定、附权限范围表的身份验证说明,以及包含状态码的错误说明。
- 端点每张端点卡片都列出其权限范围、参数、请求体、响应和错误,并附有可直接复制的 curl、JavaScript 和 Python 请求示例。
- 搜索按 / 键跳到端点搜索,可按方法、路径、权限范围或摘要筛选。
- OpenAPI JSON把完整规范下载为单个文件,供你自己的工具使用。
- 智能体 ID / API你的组织 ID 和 slug、API 模式(沙箱或正式),以及所选 AI 智能体的 ID,每一项都带有「复制」按钮。
- Webhook你的端点、每个端点接收的事件、最近一次的 HTTP 状态以及失败的投递。
请在上线之前,而不是上线之后,阅读关于速率限制和外发 Webhook 的章节。其中描述的行为在快速测试中很容易被忽略。
API 密钥与权限范围
每个请求都在 Authorization 头中以 Bearer 令牌的形式携带密钥。密钥不是在应用中创建的:由你所在工作区的运营方签发,并告知你它带有哪些权限范围。完整密钥只在签发时显示一次,之后只会显示前几个字符,因此请立即把它存入你自己的密钥管理库。
| 权限范围 | 允许的操作 |
|---|---|
| read | 读取联系人、通话、队列、团队成员、报表和拒接来电名单。 |
| write | 创建和更新联系人、记录通话结果、向拒接来电名单添加号码。 |
| calls | 发起和结束通话。 |
| admin | 管理 Webhook;也可以调用其他所有端点。 |
只申请完成工作所需的最小权限集合。报表脚本只需要 read;点击拨号按钮只需要 calls。如果请求返回 403 和代码 insufficient_scope,说明该密钥缺少该端点卡片上标明的权限范围。
沙箱与正式环境
密钥可以签发给沙箱使用(使用模拟器,不会发起真实呼叫),也可以签发给正式环境使用。密钥前缀只能当作标签:标有测试字样的密钥,与正式密钥作用于相同的数据和相同的电话连接,所以不要依赖前缀来让试验远离真实客户。请以「开发者」页面上显示的 API 模式为准。
通过 API 发起呼叫
公开端点涵盖基础功能:健康检查、列出通话、读取单通通话、发起呼叫、挂断、管理 Webhook,以及与 AI 智能体对话。通过 API 发起的外呼会经过与坐席端呼叫相同的合规检查,因此拒接来电名单上的号码或超出允许通话时段的呼叫都会被拒绝,与坐席操作时完全一样。请把这种拒绝作为正常结果来处理,而不是当作程序错误。
这一点对设计很重要。不要写一个反复重试被拒呼叫直到成功的循环。读取原因、记录日志,然后继续下一项。关于这些拒绝背后的规则,请参阅Call 中的通话时段保护和Call 中的拒接来电名单。
速率限制与错误
每个密钥都有自己的每分钟请求上限,在签发密钥时设定,默认值为 120。密钥用完当前这一分钟的额度后,API 会返回 429 和代码 rate_limited,并在 X-RateLimit-Reset 头中告诉你需要等待多久。等待相应时间后再继续。有礼貌的客户端会在撞墙之前主动放慢速度。
- 429 rate_limited:按照 reset 头中的时间退避,并把批量工作分散到更长的时间里。
- 403 insufficient_scope:密钥缺少该端点卡片上标明的权限范围;请申请带有该权限的密钥。
- 其他错误:依据错误代码而不是错误消息来处理。代码不会变,措辞可能会变。
处理失败的请求
- 读取状态码是你能修复的客户端错误,还是值得重试的服务器错误?
- 读取错误代码按代码分支处理,绝不依据消息文本。
- 退避遇到 429 时按 reset 头等待;遇到服务器错误时,以逐渐增加的间隔重试几次。
- 记录细节保留端点、错误代码和时间,方便技术支持追查。
- 遇到拒绝就停止合规拒绝是一个决定,而不是故障;不要循环重试。
Webhook:接收事件
与其一遍遍地询问 API 是否发生了某件事,不如让 Call 主动通知你。在「开发者」页面点击「添加端点」,填写一个公开的 https 地址,并勾选需要的事件;不勾选任何事件表示接收全部事件。签名密钥只在添加端点时显示一次,请当场复制。如果丢失,请删除该端点再重新添加,以获得新的密钥。
每次投递都带有签名。签名头中是用你的签名密钥对“时间戳 + 英文句点 + 请求体”计算得出的 HMAC-SHA256,另一个单独的头携带时间戳。在信任负载之前,请在你这一端重新计算并比对。API 参考中提供了 Node.js 和 Python 的示例代码;拒绝过旧的时间戳可以防范重放请求。
好的与差的 Webhook 接收端
| 好 | 差 | |
|---|---|---|
| 签名 | 每个请求都校验 | 不经检查就信任 |
| 响应 | 几秒内返回 2xx,工作排队稍后处理 | 先慢慢处理再响应 |
| 重复事件 | 同一事件收到两次也无妨 | 会生成两条记录 |
| 失败 | 投递失败时发出告警 | 悄无声息,直到有人发现 |
你的端点必须在 10 秒内返回 2xx 状态码。投递失败会重试,总共最多尝试六次;连续失败 50 次的端点会被关闭。「开发者」页面的每一行都会显示最近一次的 HTTP 状态和失败投递的次数,「发送测试」会发出一个带签名的测试事件,让你看到服务器如何响应。
上线检查清单
开启集成之前
- 清楚密钥有哪些权限范围,且没有超出所需
- 密钥存放在密钥管理库中,而不是源代码里
- Webhook 签名经过校验,过旧的时间戳会被拒绝
- 接收端响应迅速,并能处理重复事件
- 速率限制和拒绝响应得到处理,没有密集的重试循环
- 已在沙箱模式下测试,并对端点点击过「发送测试」
- 已指定专人在投递开始失败时接收告警
在 Call 中操作
在 Call 中,打开「设置」→「API 参考」研究各个端点;打开「设置」→「开发者」复制组织 ID、检查密钥并添加 Webhook。所有者、管理员和经理可以添加、测试和删除端点;其他人只能查看列表。如果你也使用 AI 智能体功能,同一页面上的智能体 ID 会用于对话端点。产品的语音部分,请参阅在 Call 中设置 AI 智能体。
常见问题
如何获取 API 密钥?
密钥由你所在工作区的运营方签发,不能在应用中创建。申请时请说明需要哪些权限范围。完整密钥只在签发时显示一次。
429 响应是什么意思?
该密钥已用完当前这一分钟的请求额度。等待 X-RateLimit-Reset 头中给出的秒数后再试,并把批量工作分散到更长的时间里。
如何确认 Webhook 确实来自 Call?
用你的签名密钥对时间戳和请求体计算 HMAC-SHA256,并与签名头比对。API 参考中有 Node.js 和 Python 的示例。
可以把 Webhook 发送到本地开发服务器吗?
不能直接发送。端点必须是公开的 https 地址,因此请使用内网穿透工具,把本地服务器暴露到这样的地址上。
为什么我通过 API 发起的呼叫被拒绝了?
通过 API 发起的呼叫会经过与坐席端相同的合规检查。拒接来电名单上的号码或超出通话时段的呼叫会被拒绝。
谁可以查看和修改 Webhook?
所有人都可以查看列表,但只有所有者、管理员和经理可以添加、测试或删除端点。