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 變更日誌來源 →