REST · WebSocket · gRPC

API
посилання.

312 кінцевих точок, повна специфікація OpenAPI, ідемпотентність для кожної мутації та загальнодоступний контракт на безвідмовну роботу. Без чорних ящиків.

Базовий URL

api.rozper.com

Версія

v2026.05

Ліміт тарифу

1000 об/с

ПОСТ/v2/дзвінки

"color:#22D3EE">curl "color:#22D3EE">-X "color:#34D399;font-weight:600">POST https://api.rozper.com/v2/calls \
  "колір:#22D3EE">-H «Дозвіл: на пред’явника $ROZPER_API_KEY" \
  "колір:#22D3EE">-H "Тип вмісту: додаток/json" \
  "колір:#22D3EE">-д '{
    "до":   "+14155551234",
    "від": "+12025550100",
    "url":  "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
Взаємний TLS доступний на Enterprise

Заголовок авторизації

cURLВузол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. Негайно повертається з об’єктом виклику в черзі — прослуховувати вебхуки для змін стану.

ПОСТ/v2/дзвінки

Параметри

toрядокпотрібно

Номер призначення E.164.

fromрядокпотрібно

Перевірений або орендований номер Розпер.

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, зрозуміле для людини повідомлення та ідентифікатор запиту, який можна вставити для підтримки.

Помилка конверта

{
  "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

Ключу бракує обсягу, необхідного для цього ресурсу.

404

not_found

Ідентифікатор ресурсу не існує для цього облікового запису.

409

conflict

Ключ ідемпотентності стикається з іншим корисним навантаженням.

422

invalid_param

Не вдалося перевірити параметр. Перевірте param_errors[].

429

rate_limited

Відмова за допомогою заголовка Retry-After.

500

server_error

Нас повідомили. Повторіть ідемпотентні виклики.

§04 · Веб-хуки

Підписано, повторна спроба, захищено від повторного відтворення.

Кожна подія доставляється з підписом HMAC, унікальним ідентифікатором події та міткою часу UTC. Ми повторюємо спробу з експоненційною відстрочкою протягом до 24 годин.

Підпис HMAC-SHA256 у Rozper-Signature

До 8 повторних спроб · 24 години

Надсилайте на кілька кінцевих точок одночасно

Перевірте вебхук · Вузол✓ порівняння в постійному часі

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
- featГолосові агенти тепер підтримують інструментальні виклики з потоковими відповідями.
- featНова кінцева точка /v2/numbers/port для програмних надсилань LNP.
2026-04-22
v2026.04
- виправитиКеш ідемпотентності тепер правильно враховує 24-годинний TTL для викликів POST.
- рутинна роботаЗастарілі кінцеві точки v1 видалено (оголошено 2025-11).
2026-03-31
v2026.03
- featБета-версія медіа-потоків WebSocket тепер загальнодоступна.
- featШаблонні повідомлення WhatsApp додано в /v2/messages.

Підпишіться на канал журналу змін API →