REST · WebSocket · gRPC

API
thẩm quyền giải quyết.

312 điểm cuối, thông số OpenAPI hoàn chỉnh, tính tạm thời trên mọi đột biến và hợp đồng thời gian hoạt động công khai. Không có hộp đen.

URL cơ sở
api.rozper.com
Phiên bản
v2026.05
Giới hạn tỷ lệ
1000 vòng/phút
BƯU KIỆN/v2/cuộc gọi
"color:#22D3EE">curl "color:#22D3EE">-X "color:#34D399;font-weight:600">BÀI ĐĂNG https://api.rozper.com/v2/calls \
  "màu:#22D3EE">-H "Ủy quyền: Người mang $ROZPER_API_KEY" \
  "màu:#22D3EE">-H "Loại nội dung: ứng dụng/json" \
  "màu:#22D3EE">-d '{
    "ĐẾN":   "+14155551234",
    "từ": "+12025550100",
    "url":  "https://your.app/voice/answer"
  }'
201Phản hồi · 84 mili giây
{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "status": "queued",
  "to":     "+14155551234",
  "from":   "+12025550100",
  "created_at": "2026-05-12T14:23:01Z"
}
§01 · Xác thực

Mã thông báo mang.
Có phạm vi. Có thể xoay được.

Mọi yêu cầu đều mang khóa dự án dưới dạng mã thông báo Bearer. Các khóa có phạm vi (đọc, ghi, thanh toán), có thể xoay mà không có thời gian ngừng hoạt động và có thể được ghim IP từ trang tổng quan.

  • Khóa cho mỗi môi trường (thử nghiệm/trực tiếp)
  • Hỗ trợ thông tin xác thực ứng dụng khách OAuth 2.0
  • TLS tương hỗ có sẵn trên Enterprise
Tiêu đề ủy quyền
cURLnútPythonĐi
# .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 · Tham khảo

Khám phá mọi điểm cuối.

cuộc gọiTạo cuộc gọi

Tạo cuộc gọi

Bắt đầu cuộc gọi PSTN đi. Trả về ngay lập tức với một đối tượng cuộc gọi được xếp hàng đợi — lắng nghe trên webhooks để biết các thay đổi trạng thái.

BƯU KIỆN/v2/cuộc gọi
Thông số
tosợi dâyyêu cầu

Số đích E.164.

fromsợi dâyyêu cầu

Số Rozper đã được xác minh hoặc thuê.

urlsợi dây

Điểm cuối HTTPS trả về hướng dẫn bằng giọng nói khi cuộc gọi kết nối.

recordboolean

Ghi cả hai chân vào kho lưu trữ của bạn. Mặc định là sai.

timeoutsố nguyên

Thời gian chờ đổ chuông tính bằng giây. Mặc định 60.

Lời yêu cầu · nút● trực tiếp
const call = await rozper.calls.create({
  to:   "+14155551234",
  from: "+12025550100",
  url:  "https://your.app/voice/answer",
})
Phản hồi · 201 đã được tạo84 mili giây
{
  "id": "call_01HXY7ZQ9V3J3X8K5N",
  "object": "call",
  "created_at": "2026-05-12T14:23:01Z"
}
§03 · Lỗi

Lỗi có thể đoán trước, máy có thể đọc được.

Mọi 4xx và 5xx đều trả về cùng một hình dạng: ổn định code, một thông báo mà con người có thể đọc được và id yêu cầu mà bạn có thể dán vào bộ phận hỗ trợ.

phong bì lỗi
{
  "error": {
    "code": "invalid_param",
    "message": "to: must be E.164",
    "request_id": "req_01HXY7…",
    "param_errors": [
      { "param": "to", "reason": "format" }
    ]
  }
}
400
bad_request

Nội dung yêu cầu không đúng định dạng hoặc thiếu trường bắt buộc.

401
unauthorized

Khóa API bị thiếu, hết hạn hoặc bị thu hồi.

403
forbidden

Key thiếu phạm vi cần thiết cho tài nguyên này.

404
not_found

Id tài nguyên không tồn tại cho tài khoản này.

409
conflict

Khóa bình thường va chạm với một tải trọng khác.

422
invalid_param

Xác thực tham số không thành công. Kiểm tra param_errors[].

429
rate_limited

Rút lui bằng cách sử dụng tiêu đề Thử lại sau.

500
server_error

Chúng tôi đã được thông báo. Thử lại các cuộc gọi bình thường.

§04 · Webhook

Đã ký, thử lại, bảo vệ chống phát lại.

Mỗi sự kiện được phân phối kèm theo chữ ký HMAC, id sự kiện duy nhất và dấu thời gian UTC. Chúng tôi thử lại với thời gian chờ theo cấp số nhân trong tối đa 24 giờ.

Chữ ký HMAC-SHA256 trong Chữ ký Rozper
Tối đa 8 lần thử lại · Khoảng thời gian 24 giờ
Gửi đến nhiều điểm cuối cùng một lúc
Xác minh webhook · Nút✓ so sánh theo thời gian liên tục
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 })
})
Danh mục sự kiện · tổng cộng 32
call.initiated

Cuộc gọi đi được nhà mạng chấp nhận.

call.ringing

Đầu xa đang đổ chuông.

call.answered

Đã trả lời từ xa (hoặc AMD đã phát hiện ra con người).

call.completed

Cuộc gọi đã kết thúc. Bao gồm thời lượng, thanh toán, siêu dữ liệu chặng.

recording.ready

Ghi lại nội dung đã tải lên và URL đã ký có sẵn.

message.delivered

Biên lai giao hàng của nhà cung cấp dịch vụ (nếu được hỗ trợ).

agent.handoff

Đặc vụ AI leo thang đến hàng đợi của con người.

number.purchased

Việc thu thập số đã hoàn tất.

§05 · Nhật ký thay đổi

Mọi thay đổi đều bằng tiếng Anh đơn giản.

  1. 2026-05-10
    v2026.05
    • kỳ tíchTác nhân thoại hiện hỗ trợ gọi công cụ với phản hồi trực tuyến.
    • kỳ tíchĐiểm cuối /v2/numbers/port mới để gửi LNP có lập trình.
  2. 2026-04-22
    v2026.04
    • sửa chữaBộ nhớ đệm tạm thời hiện vinh danh chính xác 24 giờ TTL trên POST/cuộc gọi.
    • việc vặtĐã xóa các điểm cuối v1 không được dùng nữa (được công bố vào ngày 2025-11).
  3. 2026-03-31
    v2026.03
    • kỳ tíchPhiên bản beta của luồng phương tiện WebSocket hiện đã có sẵn rộng rãi.
    • kỳ tíchTin nhắn mẫu WhatsApp được thêm vào dưới /v2/messages.
Đăng ký nguồn cấp dữ liệu nhật ký thay đổi API →
Tham khảo API · Rozper REST & Tài liệu WebSocket | Rozper hôm nay