Chiamate

Avvia chiamate AI in uscita, elenca la cronologia delle chiamate e recupera i dettagli incluse trascrizioni e registrazioni.

Creare una chiamata

POST /v1/calls

Accoda una chiamata AI in uscita tramite il motore vocale LiveKit. La chiamata viene creata e accodata in modo asincrono; usa l'id restituito con GET /v1/calls/{id}.

Scope richiesto: calls:write

Body della richiesta

Campo	Tipo	Obbligatorio	Descrizione
agentId	string	Sì	ID dell'agente AI da usare per la chiamata
toNumber	string	Sì	Numero di telefono destinatario in formato E.164
fromNumber	string	Sì	Numero chiamante (deve appartenere alla tua org)
voiceId	string	No	Sovrascrive la voce predefinita dell'agente
language	string	No	Sovrascrive la lingua predefinita dell'agente
llmModel	string	No	Sovrascrive l'LLM dell'agente (id LiveKit Inference, es. google/gemini-3-flash)
customerName	string	No	Nome della persona chiamata
dynamicVariables	object	No	Coppie chiave-valore iniettate nel prompt dell'agente
metadata	object	No	Metadati personalizzati allegati alla chiamata
scheduledAt	string	No	Timestamp ISO 8601 per programmare la chiamata
disableKnowledgeBases	boolean	No	Disabilita le knowledge base per questa chiamata (default: false)

Esempio

curl -X POST https://api.replicer.ai/v1/calls \
  -H "Authorization: Bearer rpl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "clx1234567890",
    "toNumber": "+1234567890",
    "fromNumber": "+0987654321",
    "customerName": "Mario Rossi",
    "dynamicVariables": {
      "company": "Acme Corp",
      "purpose": "Follow-up sul preventivo"
    },
    "metadata": {
      "campaign_id": "estate_2026"
    }
  }'

Risposta 201 Created

{
  "data": {
    "id": "call-uuid-here",
    "status": "queued"
  },
  "requestId": "req-abc123"
}

Con scheduledAt impostato, status è scheduled.

Errori

Codice	Causa
validation_error	agentId, toNumber o fromNumber mancanti; o llmModel non supportato
not_found	L'agente non esiste o non appartiene alla tua org
forbidden	Il fromNumber non appartiene alla tua org
internal_error (503)	Motore vocale non disponibile — nessuna chiamata creata

---

Elencare le chiamate

GET /v1/calls

Recupera una lista paginata di chiamate della tua organizzazione.

Scope richiesto: calls:read

Parametri di query

Parametro	Tipo	Descrizione
page	integer	Numero pagina (default: 1)
limit	integer	Risultati per pagina (default: 20, max: 100)
status	string	Filtra per stato della chiamata
direction	string	Filtra per direzione: INBOUND o OUTBOUND
dateFrom	string	ISO 8601 — solo chiamate dopo questa data
dateTo	string	ISO 8601 — solo chiamate prima di questa data

Esempio

curl "https://api.replicer.ai/v1/calls?status=completed&limit=10" \
  -H "Authorization: Bearer rpl_live_your_key"

Risposta 200 OK

{
  "data": [
    {
      "id": "clx-call-001",
      "customerName": "Mario Rossi",
      "customerPhone": "+1234567890",
      "duration": 240,
      "status": "completed",
      "direction": "OUTBOUND",
      "disconnectionReason": "agent_hangup",
      "sentiment": "positive",
      "summary": "Discusso il piano enterprise...",
      "transcript": "Agente: Buongiorno, sono...",
      "recording": "https://storage.example.com/recordings/...",
      "callSuccessful": true,
      "tokenCost": 12.50,
      "agentId": "clx-agent-001",
      "campaignId": "clx-campaign-001",
      "startedAt": "2026-04-05T14:00:00Z",
      "endedAt": "2026-04-05T14:04:00Z",
      "createdAt": "2026-04-05T13:59:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  },
  "requestId": "req-def456"
}

---

Ottenere una chiamata

GET /v1/calls/{id}

Recupera i dettagli di una chiamata specifica.

Scope richiesto: calls:read

Parametri del percorso

Parametro	Descrizione
id	L'ID della chiamata

Esempio

curl https://api.replicer.ai/v1/calls/clx-call-001 \
  -H "Authorization: Bearer rpl_live_your_key"

Stati della chiamata

Stato	Descrizione
queued	La chiamata è in coda per l'elaborazione
in_progress	La chiamata è attualmente attiva
completed	La chiamata è terminata normalmente
failed	La chiamata non è riuscita a connettersi
cancelled	La chiamata è stata cancellata prima della connessione