ОТДЫХ · WebSocket · gRPC

API
ссылка.

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

Базовый URL

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">-д '{
    "к":   "+14155551234",
    "от": "+12025550100",
    "URL-адрес":  "https://your.app/voice/ответ"
  }'

201Ответ · 84 мс

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

§01 · Аутентификация

Токены на предъявителя.
Ограничено. Вращающийся.

Каждый запрос содержит ключ проекта в качестве токена-носителя. Ключи имеют ограниченную область действия (чтение, запись, выставление счетов), могут меняться без простоев и могут быть закреплены по IP-адресу с панели управления.

Ключи для каждой среды (тестовые/действующие)
Поддерживаются учетные данные клиента OAuth 2.0.
Взаимный TLS доступен на предприятии

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

КУЛЬУзелПитонИдти

# .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 · Справка

Исследуйте каждую конечную точку.

звонкиСоздать звонок

Создать звонок

Выполните исходящий вызов по телефонной сети общего пользования. Немедленно возвращает объект вызова в очереди — прослушивайте веб-перехватчики на предмет изменений состояния.

ПОЧТА/v2/вызовы

Параметры

toнитьнеобходимый

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

fromнитьнеобходимый

Проверенный или арендованный номер Розпера.

urlнить

Конечная точка HTTPS, которая возвращает голосовые инструкции при подключении вызова.

recordлогическое значение

Запишите обе ноги в свое хранилище. По умолчанию ложь.

timeoutцелое число

Таймаут звонка в секундах. По умолчанию 60.

Запрос · узел● жить

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

Отклик · Создано 20184 мс

{
  "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
- подвигГолосовые агенты теперь поддерживают вызов инструментов с потоковой передачей ответов.
- подвигНовая конечная точка /v2/numbers/port для программных отправок LNP.
2026-04-22
v2026.04
- исправитьКэш идемпотентности теперь правильно учитывает 24-часовой TTL при POST/вызовах.
- работа по домуУстаревшие конечные точки версии 1 удалены (объявлено в 2025–2011 гг.).
2026-03-31
v2026.03
- подвигБета-версия медиапотоков WebSocket теперь общедоступна.
- подвигСообщения шаблона WhatsApp добавлены в /v2/messages.

Подписаться на ленту изменений API →