Apeluri și artefacte

Un apel e o conversație și tot ce a lăsat în urmă: o transcriere, o înregistrare, un timeline de evenimente tipate, latența pe etape și o defalcare a costului pe componente.

API

Parametri și răspunsuri complete: referința apelurilor.

GET    /api/v1/calls
POST   /api/v1/calls
GET    /api/v1/calls/search
GET    /api/v1/calls/{id}
DELETE /api/v1/calls/{id}
POST   /api/v1/calls/{id}/end
GET    /api/v1/calls/{id}/transcript
GET    /api/v1/calls/{id}/messages
GET    /api/v1/calls/{id}/events
GET    /api/v1/calls/{id}/metrics
GET    /api/v1/calls/{id}/costs
GET    /api/v1/calls/{id}/artifacts
GET    /api/v1/calls/{id}/debug
GET    /api/v1/calls/{id}/recording
DELETE /api/v1/calls/{id}/recording
GET    /api/v1/calls/{id}/artifacts/{artifact}/download   (URL semnat, fără cheie de API)

GET /calls/search e același handler cu GET /calls

Cele două rute duc la aceeași metodă de controller. Folosește-o pe care o citești mai bine; se comportă identic.

Mașina de stări

created → queued → ringing → connecting → connected
                                             │
        ┌────────────────────────────────────┴──────────────────────────┐
        │  listening ⇄ user_speaking ⇄ thinking ⇄ tool_executing        │
        │            ⇄ assistant_speaking ⇄ on_hold ⇄ transferring      │
        │            ⇄ human_queue ⇄ human_connected                    │
        └───────────────────────────────────────────────────────────────┘
                                             │
                                 ending → ended | failed

Orice stare din buclă poate urma oricărei alteia, pentru că apelantul poate întrerupe în orice clipă — asta e barge-in-ul. ending, failed și ended sunt accesibile din orice stare neterminală. Tabela e definită o singură dată în packages/contracts/src/call-state.ts și oglindită în App\Enums\CallState, cu un test care citește sursa PHP ca să dovedească faptul că sunt de acord. Cele 17 stări sunt listate pe Stările și evenimentele apelului.

Motivele de încheiere sunt excepția: contractele au 19 și control plane-ul are 20, scrise altfel, și niciun test nu le ține laolaltă. API-ul întoarce cele douăzeci din control plane — sunt listate pe Când ceva eșuează.

Evenimente

Fiecare apel emite un flux de evenimente tipate — ciclu de viață, vorbire, transcrieri, model, TTS, tools, MCP, knowledge, rutare, contact center, DTMF, artefacte, sănătatea furnizorilor. Vocabularul e CallEventType din @callagent/contracts, oglindit în App\Enums\CallEventType. call_events e doar cu inserări. Toate cele 70 de tipuri de eveniment și payload-urile lor: tipuri de eveniment.

Artefacte

Artefact	Produs când
Transcriere	Mereu, incremental, în timpul apelului
Înregistrare	artifact_plan.recording_enabled. Se poate reda un anunț; un refuz nu poate fi respectat — vezi Dezvăluire AI și consimțământ.
Rezumat	analysis_plan, după apel — nu e dispecerizat, vezi mai jos
Structured output	Un asistent cu un structured output atașat — nu e dispecerizat, vezi mai jos
Pachet de debug	La cerere, din GET /calls/{id}/debug

Înregistrările pot fi scrise în bucket-ul tău — S3, R2, Azure Blob sau orice endpoint compatibil S3 — sub o cale prefixată cu organizația, și pot fi șterse per apel pentru o cerere de ștergere GDPR. Vezi Înregistrare și storage.

Rezumatul și structured output-ul

Rândurile Rezumat și Structured output de mai sus depind de pipeline-ul de analiză de după apel, pe care control plane-ul nu îl dispecerizează în momentul de față. Vezi Analytics.

Latență și cost

GET /calls/{id}/metrics desface turul: prima parțială de STT, endpoint detectat, timpul modelului până la primul token, timpul TTS până la primul audio, și cifra cap-coadă de la endpoint la audio, care e cea pe care o simte efectiv apelantul.

GET /calls/{id}/costs desface banii pe componente, cu unitățile proprii ale furnizorului, la decimal(20,8) — un token de LLM costă mai puțin de o milionime de dolar, iar rotunjirea lui devreme face ledger-ul greșit.

Apeluri live

Vederea Live Calls din dashboard citește snapshot-urile de sesiune ale gateway-ului — stare, tool curent, ultima transcriere, latență pe componente, furnizori activi.

Supervizorii pot asculta, pot vorbi doar operatorului sau pot intra în apel de acolo. Poarta de permisiuni și urma de audit sunt dovedite; că audio-ul chiar se conectează, nu, iar calea mai nouă de media prin gateway e oprită implicit. Vezi Contact center.