Operator SDK
SDK browser headless per far fare e ricevere chiamate ai tuoi operatori, con Audin come gateway telefonico. Nessuna UI inclusa.
@audin.ai/operator-sdk è un SDK browser headless che permette ai tuoi
operatori umani di fare e ricevere chiamate telefoniche direttamente dal
browser, via WebSocket. Audin resta il gateway telefonico (rete, routing,
fallback, registrazione, fatturazione); l'SDK si occupa solo del microfono,
dell'audio, della segnalazione, della riconnessione e dei keep-alive.
Stai integrando con un agent AI?
Scarica (o copia) il playbook pensato per un agent di coding: lo guida a intervistarti sul tuo stack e ad adattare l'integrazione, invece di prescrivere un'unica strada.
Non include alcuna UI. Tu costruisci l'interfaccia (pulsanti, lista chiamate, indicatori di stato); l'SDK fa il "plumbing". È pensato per essere innestato in qualsiasi front-end.
Come funziona, in sintesi
A livello concettuale ci sono due lati:
┌─────────────────────────────┐ ┌──────────────────────────────┐
│ Browser dell'operatore │ WS │ Gateway Audin │
│ (Operator SDK) │ ◀─────▶ │ │
│ • cattura microfono │ │ • telefonia (rete, PSTN) │
│ • riproduzione audio │ │ • routing e instradamento │
│ • segnalazione (presenza, │ │ • registrazione chiamate │
│ offerte di chiamata) │ │ • fatturazione │
└─────────────────────────────┘ └──────────────────────────────┘Il browser fornisce voce e UI; Audin fa da gateway telefonico. L'SDK apre due canali WebSocket verso il gateway: un canale di presenza/segnalazione (disponibilità, offerte di chiamata, controllo) e, per ogni chiamata, un canale audio full-duplex.
Caratteristiche
Framework-agnostic
Nessun vincolo su React, Vue o altro: è una libreria pura che puoi innestare ovunque.
Zero dipendenze runtime
Bundle leggero, nessuna dipendenza di terze parti a runtime.
ESM + UMD
Importabile come modulo ESM o caricabile via <script> (global AudinOperatorSDK).
TypeScript types
Tipi completi inclusi nel pacchetto per autocompletamento e type-safety.
Prerequisiti
Per usare l'SDK ti servono:
- Un Account Audin con almeno un numero voice (lo userai come identità in ingresso/uscita).
- Un endpoint sul tuo backend che emette un token di sessione effimero per
l'SDK. Le credenziali dell'Account non entrano mai nel browser: l'SDK ottiene
un token a vita breve tramite una callback
getTokenche fornisci tu. Il flusso è descritto nella pagina Token flow & setup backend. - Un browser moderno servito su HTTPS (o
localhost): l'accesso al microfono richiede un contesto sicuro.
Compatibilità
L'SDK comunica con il servizio operatori Audin tramite un wire protocol
versionato, attualmente v1. Il pacchetto segue SemVer:
release patch e minor mantengono la compatibilità del protocollo, mentre una
modifica incompatibile al protocollo comporta un bump MAJOR (es. 1.x → 2.0).
In pre-1.0 anche l'API pubblica può evolvere nelle minor: blocca un range MAJOR
compatibile (^0.3) e leggi il changelog prima di aggiornare. Questa
documentazione copre la versione 0.3.0.
Limiti noti (MVP). In questa fase l'SDK ha alcune limitazioni da tenere presenti quando progetti la tua UX:
- Una sola chiamata attiva per operatore. Mentre una chiamata è in corso,
le offerte in entrata vengono rifiutate automaticamente e
dial()fallisce. - DTMF non ancora inoltrato alla rete.
sendDtmf()è validato ed emesso, ma i toni non raggiungono ancora la controparte (no-op end-to-end per ora). - Nessun ringback. Durante la connessione di una chiamata in uscita non c'è tono di libero: l'operatore sente silenzio finché l'audio non è stabilito.
- Nessun re-routing mid-call. Non è previsto lo spostamento di una chiamata attiva tra operatori (solo grace period e riconnessione).
Prossimi passi
Token flow & setup backend
Il pattern apiKey-server-side / token-effimero-client e l'endpoint da implementare.
Quickstart
Installazione, inizializzazione e un esempio end-to-end minimale.
Numeri & presenza
Elencare i numeri, andare online e gestire la disponibilità.
API reference
Configurazione, metodi, eventi e tipi al completo.