---
title: Operator SDK
description: 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.

<AgentGuide file="/operator-sdk-agent-guide.md" filename="operator-sdk-agent-guide.md" />

<Callout type="info">
  **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.
</Callout>

## Come funziona, in sintesi

A livello concettuale ci sono due lati:

```text
┌─────────────────────────────┐         ┌──────────────────────────────┐
│  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

<Cards>
  <Card title="Framework-agnostic" description="Nessun vincolo su React, Vue o altro: è una libreria pura che puoi innestare ovunque." />
  <Card title="Zero dipendenze runtime" description="Bundle leggero, nessuna dipendenza di terze parti a runtime." />
  <Card title="ESM + UMD" description="Importabile come modulo ESM o caricabile via <script> (global AudinOperatorSDK)." />
  <Card title="TypeScript types" description="Tipi completi inclusi nel pacchetto per autocompletamento e type-safety." />
</Cards>

## 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 `getToken` che fornisci tu. Il
  flusso è descritto nella pagina [Token flow & setup backend](/docs/operator-sdk/token-flow).
- 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](https://semver.org):
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.6`) e leggi il changelog prima di aggiornare. Questa
documentazione copre la versione **0.6.0**.

<Callout type="warn">
  **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.
  - **Nessun feedback locale DTMF.** `sendDtmf()` inoltra la cifra alla rete
    telefonica (tono in-band iniettato lato server) e la controparte la sente,
    ma l'operatore **non** sente il proprio tono: il feedback alla pressione
    dei tasti è a carico della tua UI.
  - **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).
</Callout>

## Prossimi passi

<Cards>
  <Card href="/docs/operator-sdk/token-flow" title="Token flow & setup backend" description="Il pattern apiKey-server-side / token-effimero-client e l'endpoint da implementare." />
  <Card href="/docs/operator-sdk/quickstart" title="Quickstart" description="Installazione, inizializzazione e un esempio end-to-end minimale." />
  <Card href="/docs/operator-sdk/numeri-presenza" title="Numeri & presenza" description="Elencare i numeri, andare online e gestire la disponibilità." />
  <Card href="/docs/operator-sdk/api-reference" title="API reference" description="Configurazione, metodi, eventi e tipi al completo." />
</Cards>