REST · WebSocket · gRPC

API
odniesienie.

312 punktów końcowych, pełna specyfikacja OpenAPI, idempotencja dla każdej mutacji i publiczna umowa dotycząca dostępności. Żadnych czarnych skrzynek.

Bazowy adres URL

api.rozper.com

Wersja

wersja 2026.05

Limit stawki

1000 obr./min

POST/v2/połączenia

"color:#22D3EE">curl "color:#22D3EE">-X "kolor:#34D399;grubość czcionki:600">POST https://api.rozper.com/v2/calls \
  „kolor:#22D3EE”>-H „Upoważnienie: Na okaziciela $ROZPER_API_KEY" \
  „kolor:#22D3EE”>-H „Typ zawartości: aplikacja/json” \
  „kolor:#22D3EE”>-d '{
    "Do":   "+14155551234",
    "z": "+12025550100",
    „adres URL”:  „https://twoja.aplikacja/głos/odpowiedź”
  }'

201Odpowiedź · 84 ms

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

§01 · Uwierzytelnianie

Żetony okaziciela.
Zakres. Obrotowy.

Każde żądanie zawiera klucz projektu jako token okaziciela. Klucze mają określony zakres (odczyt, zapis, fakturowanie), można je obracać bez przestojów i można je przypinać do adresu IP z poziomu pulpitu nawigacyjnego.

Klucze dla poszczególnych środowisk (testowe/aktywne)
Obsługiwane poświadczenia klienta OAuth 2.0
Wzajemny TLS dostępny w Enterprise

Nagłówek autoryzacji

kędziorWęzełPytonIść

# .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 · Odniesienie

Przeglądaj każdy punkt końcowy.

dzwoniUtwórz połączenie

Utwórz połączenie

Rozpocznij połączenie wychodzące PSTN. Zwraca natychmiast z obiektem wywołania w kolejce — nasłuchuj na elementach webhook pod kątem zmian stanu.

POST/v2/połączenia

Parametry

tosmyczkowywymagany

Numer docelowy E.164.

fromsmyczkowywymagany

Zweryfikowany lub wypożyczony numer Rozper.

urlsmyczkowy

Punkt końcowy HTTPS, który zwraca instrukcje głosowe po nawiązaniu połączenia.

recordwartość logiczna

Nagraj obie nogi w swoim magazynie. Domyślnie fałsz.

timeoutliczba całkowita

Limit czasu dzwonienia w sekundach. Domyślnie 60.

Wniosek · węzeł● na żywo

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

Odpowiedź · Utworzono 20184 ms

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

§03 · Błędy

Przewidywalne błędy do odczytu maszynowego.

Każde 4xx i 5xx zwraca ten sam kształt: stajnię code, wiadomość czytelną dla człowieka i identyfikator żądania, który możesz wkleić do pomocy technicznej.

Koperta z błędem

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

400

bad_request

Nieprawidłowo sformułowana treść żądania lub brak wymaganego pola.

401

unauthorized

Brakujący, wygasły lub unieważniony klucz API.

403

forbidden

Klucz nie ma zakresu wymaganego dla tego zasobu.

404

not_found

Identyfikator zasobu nie istnieje dla tego konta.

409

conflict

Klucz idempotencji koliduje z innym ładunkiem.

422

invalid_param

Sprawdzanie poprawności parametru nie powiodło się. Sprawdź param_errors[].

429

rate_limited

Wycofywanie za pomocą nagłówka Retry-After.

500

server_error

Zostaliśmy powiadomieni. Ponów próbę wywołań idempotentnych.

§04 · Webhooki

Podpisano, ponowiono próbę, zabezpieczono przed ponownym odtwarzaniem.

Każde zdarzenie jest dostarczane z podpisem HMAC, unikalnym identyfikatorem zdarzenia i znacznikiem czasu UTC. Ponawiamy próbę z wykładniczym wycofywaniem przez maksymalnie 24 godziny.

Sygnatura HMAC-SHA256 w Rozper-Signature

Do 8 ponownych prób · Okno 24-godzinne

Wysyłaj do wielu punktów końcowych jednocześnie

Zweryfikuj webhooka · Node✓ porównanie w czasie stałym

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 })
})

Katalog wydarzeń · Łącznie 32

call.initiated

Połączenie wychodzące zaakceptowane przez operatora.

call.ringing

Daleki koniec dzwoni.

call.answered

Odpowiedział zdalny terminal (lub AMD wykrył człowieka).

call.completed

Połączenie zostało zakończone. Obejmuje czas trwania, rozliczenia i metadane dotyczące nogi.

recording.ready

Dostępny jest zasób nagrania i podpisany adres URL.

message.delivered

Potwierdzenie dostawy przewoźnika (jeśli jest obsługiwane).

agent.handoff

Agent AI przekształcił się w ludzką kolejkę.

number.purchased

Zakończono pobieranie numeru.

§05 · Lista zmian

Każda zmiana, prostym angielskim.

2026-05-10
wersja 2026.05
- wyczynAgenci głosowi obsługują teraz wywoływanie narzędzi z odpowiedziami przesyłanymi strumieniowo.
- wyczynNowy punkt końcowy /v2/numbers/port dla programowych zgłoszeń LNP.
2026-04-22
wersja 2026.04
- naprawićPamięć podręczna idempotencji teraz prawidłowo honoruje 24-godzinny czas TTL w przypadku połączeń POST/call.
- obowiązekUsunięto przestarzałe punkty końcowe w wersji 1 (ogłoszone na rok 2025–2011).
2026-03-31
wersja 2026.03
- wyczynWersja beta strumieni multimediów WebSocket jest już ogólnie dostępna.
- wyczynWiadomości szablonowe WhatsApp dodane w /v2/messages.

Subskrybuj kanał dziennika zmian API →