API 密钥与权限范围

Ringhum REST API 让您自己的系统与您的工作区互通：列出通话和转录记录、创建助手、预约、管理联系人、拨打外呼电话等等。每个请求都通过属于某个工作区的 API 密钥进行身份验证。本文介绍如何创建密钥，以及所有接口共通的约定。完整的接口参考文档见 /docs。

谁可以管理密钥

所有方案都可以使用 API。但密钥能做什么仍受您的方案限制：例如，创建助手超出方案上限时会返回错误。

创建 API 密钥

1. 在侧边栏打开开发者。
2. 在 API 密钥卡片中，点击创建密钥。
3. 输入密钥名称，说明该密钥的用途，例如"生产服务器"。
4. 在权限范围下，勾选读取、写入或两者。
5. 点击创建密钥。
6. 从绿色框中复制密钥，并妥善保存，例如保存到服务器的密钥库中。点击完成。

重要： 密钥仅显示一次。Ringhum 只存储密钥的指纹，因此无法再次显示。如果丢失，请创建新密钥并撤销旧密钥。

密钥以 ck_live_ 开头。API 密钥表格显示每个密钥的名称、密钥开头的几个字符、其权限范围、最近使用时间，以及是启用还是已撤销状态。

权限范围

任何密钥都可以调用只读接口。创建、修改或删除内容的接口需要写入权限，例如拨打电话、发送消息、预约或更新助手。/docs 中的参考文档会标注这些接口。没有写入权限的密钥调用这些接口时会收到 403 错误。

请为每个系统分配所需的最小权限。报表看板只需要读取权限。

撤销密钥

1. 在开发者页面的 API 密钥表格中找到该密钥。
2. 点击撤销并确认。

使用该密钥的请求会立即以 401 失败。已撤销的密钥仍会保留在列表中，标记为已撤销，以便您查看历史记录。密钥无法编辑：如需更改其权限范围，请创建新密钥并撤销旧密钥。

发起请求

• 基础网址： https://ringhum.com/api/v1
• 身份验证： 将密钥作为 Bearer 令牌发送：Authorization: Bearer ck_live_…
• 格式： 请求和响应均为 JSON。发送请求体时请附带 Content-Type: application/json。
• 时间采用 UTC 的 ISO 8601 格式。电话号码采用 E.164 格式，例如 +14155550132。ID 为整数。
• 更新使用 PATCH，仅需包含要修改的字段。
• 每个响应都带有 X-Request-Id 请求头。联系支持团队时请附上该值。

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

要查看某个密钥属于哪个工作区，请调用 GET /me。

响应与分页

单个对象以 {"data": {…}} 的形式返回。分页列表会附带一个 meta 对象：

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

使用 page 和 per_page 来翻阅结果。per_page 默认值为 25，最大值为 100。

错误

所有失败响应结构相同，并带有一个可在代码中判断的稳定 type 字段：

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

速率限制

每分钟最多可发起 120 次请求。响应中包含 X-RateLimit-Limit 和 X-RateLimit-Remaining 请求头。超出限制时会收到 429 响应，并附带 Retry-After 请求头，说明需要等待的秒数。

提示： 请勿轮询通话结果。为 call.ended 添加 webhook，通话结束后 Ringhum 会将摘要和转录记录发送给您。参见Webhook。

常见问题

是否有机器可读的规范？ 有。OpenAPI 3.1 描述文件位于 /api/v1/openapi.json，无需密钥即可访问。您可以据此生成客户端代码。

创建密钥的人离职后，该密钥会失效吗？ 不会。密钥归属于工作区，会持续有效，直到被撤销。当不再信任某个密钥，尤其是有权访问的人员离职时，请撤销该密钥。

可以在网页中使用该 API 吗？ 不可以。任何打开该网页的人都能读取到密钥。请从您的服务器调用 API。