RESTO · WebSocket · gRPC

API
riferimento.

312 endpoint, specifiche OpenAPI complete, idempotenza su ogni mutazione e un contratto pubblico di uptime. Nessuna scatola nera.

URL di base

api.rozper.com

Versione

v2026.05

Limite di tariffa

1000 rupie

INVIARE/v2/chiamate

"color:#22D3EE">curl "color:#22D3EE">-X "colore:#34D399;peso-carattere:600">POST https://api.rozper.com/v2/calls \
  "colore:#22D3EE">-H "Autorizzazione: Portatore $ROZPER_API_KEY" \
  "colore:#22D3EE">-H "Tipo di contenuto: application/json" \
  "colore:#22D3EE">-d '{
    "A":   "+14155551234",
    "da": "+12025550100",
    "URL":  "https://tua.app/voce/risposta"
  }'

201Risposta · 84 ms

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

§01 · Autenticazione

Gettoni al portatore.
Ambito. Girevole.

Ogni richiesta trasporta una chiave di progetto come token al portatore. Le chiavi hanno un ambito (lettura, scrittura, fatturazione), possono essere ruotate senza tempi di inattività e possono essere bloccate su IP dal dashboard.

Chiavi per ambiente (test/live)
Credenziali client OAuth 2.0 supportate
TLS reciproco disponibile su Enterprise

Intestazione dell'autorizzazione

arricciareNodoPitoneAndare

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

Esplora ogni endpoint.

chiamateCrea una chiamata

Crea una chiamata

Origina una chiamata PSTN in uscita. Restituisce immediatamente un oggetto chiamata in coda: ascolta sui webhook le modifiche di stato.

INVIARE/v2/chiamate

Parametri

tocordanecessario

Numero di destinazione E.164.

fromcordanecessario

Numero Rozper verificato o noleggiato.

urlcorda

Endpoint HTTPS che restituisce istruzioni vocali quando la chiamata si connette.

recordbooleano

Registra entrambe le gambe nella tua memoria. Predefinito falso.

timeoutintero

Timeout squillo in secondi. Predefinito 60.

Richiesta · nodo● vivere

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

Risposta · 201 creati84 ms

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

§03 · Errori

Errori prevedibili e leggibili dalla macchina.

Ogni 4xx e 5xx restituisce la stessa forma: una stalla code, un messaggio leggibile e un ID richiesta che puoi incollare per supportare.

Busta di errore

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

400

bad_request

Corpo della richiesta non valido o campo obbligatorio mancante.

401

unauthorized

Chiave API mancante, scaduta o revocata.

403

forbidden

La chiave non ha l'ambito richiesto per questa risorsa.

404

not_found

L'ID risorsa non esiste per questo account.

409

conflict

La chiave di idempotenza entra in collisione con un carico utile diverso.

422

invalid_param

La convalida di un parametro non è riuscita. Ispeziona param_errors[].

429

rate_limited

Backoff utilizzando l'intestazione Retry-After.

500

server_error

Siamo stati avvisati. Riprovare le chiamate idempotenti.

§04 · Webhook

Firmato, riprovato, protetto da riproduzione.

Ogni evento viene fornito con una firma HMAC, un ID evento univoco e un timestamp UTC. Riproviamo con backoff esponenziale per un massimo di 24 ore.

Firma HMAC-SHA256 nella firma Rozper

Fino a 8 tentativi · Finestra di 24 ore

Invia a più endpoint contemporaneamente

Verificare un webhook · Node✓ confronto a tempo costante

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

Catalogo eventi · 32 in totale

call.initiated

Chiamata in uscita accettata dal corriere.

call.ringing

Il posto remoto sta squillando.

call.answered

Risposta dall'estremità remota (o AMD ha rilevato un essere umano).

call.completed

Chiamata terminata. Include durata, fatturazione, metadati della gamba.

recording.ready

Risorsa di registrazione caricata e URL firmato disponibile.

message.delivered

Ricevuta di consegna del corriere (ove supportato).

agent.handoff

L'agente AI è passato a una coda umana.

number.purchased

Acquisizione del numero completata.

§05 · Registro delle modifiche

Ogni cambiamento, in parole povere.

2026-05-10
v2026.05
- impresaGli agenti vocali ora supportano le chiamate agli strumenti con risposte in streaming.
- impresaNuovo endpoint /v2/numbers/port per invii LNP programmatici.
2026-04-22
v2026.04
- aggiustareLa cache di idempotenza ora rispetta correttamente il TTL 24 ore su POST /chiamate.
- lavorettoEndpoint v1 deprecati rimossi (annunciati nel 2025-11).
2026-03-31
v2026.03
- impresaLa versione beta dei flussi multimediali WebSocket è ora disponibile a livello generale.
- impresaMessaggi modello WhatsApp aggiunti in /v2/messages.

Iscriviti al feed del log delle modifiche API →