REST·WebSocket·gRPC

应用程序编程接口
参考。

312 个端点、完整的 OpenAPI 规范、每次突变的幂等性以及公共正常运行时间合同。没有黑匣子。

基本网址

api.rozper.com

版本

v2026.05

速率限制

1000转/秒

邮政/v2/通话

"color:#22D3EE">curl "color:#22D3EE">-X “颜色：#34D399；字体粗细：600”>邮政 https://api.rozper.com/v2/calls \
  “颜色：#22D3EE”>-H “授权：持有者 $ROZPER_API_KEY" \
  “颜色：#22D3EE”>-H “内容类型：应用程序/json” \
  “颜色：#22D3EE”>-d '{
    “到”:   "+14155551234",
    “从”: "+12025550100",
    “网址”:  “https://your.app/voice/answer”
  }'

201响应 · 84 毫秒

{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "status": "queued",
  "to":     "+14155551234",
  "from":   "+12025550100",
  "created_at": "2026-05-12T14:23:01Z"
}

§01·认证

不记名令牌。
范围。可旋转。

每个请求都带有一个项目密钥作为承载令牌。密钥是有范围的（读、写、计费），可以在不停机的情况下轮换，并且可以从仪表板进行 IP 固定。

每个环境的密钥（测试/实时）
支持 OAuth 2.0 客户端凭据
Enterprise 上提供相互 TLS

授权标头

卷曲节点Python去

# .env  →  never commit me
ROZPER_API_KEY=sk_live_8FzqQ...XW7p

# request
curl https://api.rozper.com/v2/account \
  -H "Authorization: Bearer $ROZPER_API_KEY"

# 200 OK
{
  "id": "acct_01HXY7ZQ9V3J3X8K5N",
  "scopes": ["calls.write", "messages.write", "numbers.read"],
  "rate_limit": { "limit": 1000, "remaining": 998, "reset": 1715520000 }
}

§02·参考

探索每一个端点。

来电创建通话

创建通话

发起出站 PSTN 呼叫。立即返回一个排队的调用对象 - 监听 webhooks 的状态更改。

邮政/v2/通话

参数

to细绳必需的

E.164 目的地号码。

from细绳必需的

已验证或租用的 Rozper 号码。

url细绳

当呼叫连接时返回语音指令的 HTTPS 端点。

record布尔值

将两条腿记录到您的存储中。默认为 false。

timeout整数

响铃超时（以秒为单位）。默认 60。

要求 · 节点●直播

const call = await rozper.calls.create({
  to:   "+14155551234",
  from: "+12025550100",
  url:  "https://your.app/voice/answer",
})

响应 · 201 已创建84 毫秒

{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "object": "call",
  "created_at": "2026-05-12T14:23:01Z"
}

§03·错误

可预测的、机器可读的错误。

每个 4xx 和 5xx 返回相同的形状：稳定 code、一条人类可读的消息以及一个您可以粘贴到支持的请求 ID。

误差包络线

{
  "error": {
    "code": "invalid_param",
    "message": "to: must be E.164",
    "request_id": "req_01HXY7…",
    "param_errors": [
      { "param": "to", "reason": "format" }
    ]
  }
}

400

bad_request

请求正文格式错误或缺少必填字段。

401

unauthorized

API 密钥丢失、过期或撤销。

403

forbidden

Key 缺少该资源所需的范围。

404

not_found

此帐户的资源 ID 不存在。

409

conflict

幂等性密钥与不同的有效负载发生冲突。

422

invalid_param

参数验证失败。检查 param_errors[]。

429

rate_limited

使用 Retry-After 标头进行退避。

500

server_error

我们收到通知了。重试幂等调用。

§04 · 网络钩子

签名、重试、重播保护。

每个事件都带有 HMAC 签名、唯一事件 ID 和 UTC 时间戳。我们会使用指数退避重试长达 24 小时。

Rozper-Signature 中的 HMAC-SHA256 签名

最多 8 次重试 · 24 小时窗口

同时发送到多个端点

验证 webhook · 节点✓ 恒定时间比较

import { verify } from "@rozper/sdk/webhooks"

app.post("/webhooks/rozper", (req, res) => {
  const ok = verify({
    payload:   req.rawBody,
    signature: req.header("Rozper-Signature"),
    secret:    process.env.ROZPER_WEBHOOK_SECRET,
  })
  if (!ok) return res.status(401).end()

  const event = JSON.parse(req.rawBody)
  switch (event.type) {
    case "call.completed": /* … */
    case "recording.ready": /* … */
  }
  res.json({ received: true })
})

活动目录 · 共 32 个

call.initiated

运营商接受的拨出呼叫。

call.ringing

远端正在响铃。

call.answered

远端应答（或 AMD 检测到人类）。

call.completed

通话结束。包括持续时间、计费、航段元数据。

recording.ready

记录资产已上传并签名 URL 可用。

message.delivered

承运商交货收据（如果支持）。

agent.handoff

人工智能代理升级为人工队列。

number.purchased

号码获取完成。

§05 · 变更日志

每一个变化，都用简单的英语表达。

2026-05-10
v2026.05
- 壮举语音代理现在支持带有流响应的工具调用。
- 壮举用于编程 LNP 提交的新 /v2/numbers/port 端点。
2026-04-22
v2026.04
- 使固定幂等性缓存现在可以正确支持 POST/调用上的 24 小时 TTL。
- 杂务已删除已弃用的 v1 端点（2025 年 11 月宣布）。
2026-03-31
v2026.03
- 壮举WebSocket 媒体流测试版现已全面发布。
- 壮举WhatsApp 模板消息添加到 /v2/messages 下。

订阅 API 变更日志源 →