---
title: API reference
description: Configurazione, metodi, eventi e tipi di @audin.ai/operator-sdk — versione 0.6.0, wire protocol v1.
---

Reference completa della superficie pubblica di `@audin.ai/operator-sdk`.

<Callout type="info">
  Questa pagina copre **`@audin.ai/operator-sdk` 0.6.0**, che parla con il
  servizio operatori Audin tramite il **wire protocol `v1`**. Un cambio
  incompatibile al protocollo comporta un bump **MAJOR**. Consulta il
  [CHANGELOG](https://unpkg.com/browse/@audin.ai/operator-sdk/CHANGELOG.md) prima
  di aggiornare attraverso una MAJOR.
</Callout>

## `new AudinOperator(config)`

Crea un'istanza dell'SDK. L'unico parametro è l'oggetto di configurazione
`AudinOperatorConfig`.

| Opzione | Tipo | Default | Note |
|---|---|---|---|
| `coreUrl` | `string` | — | URL base del servizio operatori Audin. Uno schema `http(s)` viene convertito internamente nel corrispondente `ws(s)`; gli slash finali sono tollerati. |
| `getToken` | `() => Promise<{ token: string; expiresAt?: string }>` | — | Recupera un token di sessione fresco dal **tuo** backend. Chiamata alla connessione e a ogni riconnessione: restituisci sempre un token nuovo, mai uno scaduto in cache. |
| `heartbeatIntervalMs` | `number` | `25000` | Intervallo (ms) dei keep-alive del canale di presenza. Il server scarta le connessioni inattive da ~90s, quindi tienilo ben sotto. |
| `reconnectBackoffMs` | `number[]` | `[1000, 2000, 5000, 10000, 30000]` | Schedulazione del backoff (ms) per la riconnessione della presenza. L'SDK percorre l'array sui fallimenti consecutivi e resta sull'ultimo valore. |
| `audioConstraints` | `MediaTrackConstraints` | echo cancel + noise suppress + AGC | Vincoli passati a `getUserMedia({ audio })` per la cattura del microfono. |
| `logger` | `OperatorLogger` | `console` | Sink per la diagnostica dell'SDK. |

## Metodi

| Metodo | Firma | Descrizione |
|---|---|---|
| `listPhoneNumbers` | `(): Promise<OperatorPhoneNumber[]>` | Elenca i numeri dell'account (`{ id, phoneNumber, displayName }`), recuperati con lo stesso token di sessione dei WebSocket. Su `401` persistente lancia `OperatorRequestError` con `code: "UNAUTHORIZED"`; altri fallimenti lanciano con `code: "REQUEST_FAILED"`. |
| `goOnline` | `(phoneNumberIds: string[]): Promise<void>` | Connette il canale di presenza e annuncia la disponibilità sui numeri indicati (per `id`). Richiamabile per cambiare l'insieme di numeri. |
| `goOffline` | `(): Promise<void>` | Annulla la disponibilità, termina l'eventuale chiamata attiva e chiude il canale di presenza (interrompe la riconnessione automatica). |
| `dial` | `(to: string, opts: DialOptions): Promise<OperatorCall>` | Avvia una chiamata in uscita. Si risolve quando la piattaforma accetta e il bridge audio si apre. |
| `setAudioConstraints` | `(constraints: MediaTrackConstraints): void` | Aggiorna i vincoli del microfono (es. cambio device). Hanno effetto dalla **prossima** apertura del canale audio. |
| `get state` | `PresenceState` | Stato corrente del canale di presenza. |
| `get currentCall` | `OperatorCall \| null` | La chiamata attualmente in corso, se presente. |
| `on` | `(event, listener): () => void` | Sottoscrive un evento; restituisce una funzione di unsubscribe. |
| `off` | `(event, listener): void` | Rimuove un listener. |
| `once` | `(event, listener): void` | Sottoscrive un evento una sola volta. |

## Eventi

Sottoscrivibili con `op.on(name, cb)`. Le firme sono tipate (`AudinOperatorEventMap`).

| Evento | Payload | Quando |
|---|---|---|
| `presenceStateChanged` | `PresenceState` | Lo stato del canale di presenza cambia. |
| `availabilityChanged` | `{ accepted: string[]; rejected: string[] }` | Il server conferma su quali numeri sei andato online. |
| `incomingCall` | `OperatorCall` | Una chiamata in entrata sta squillando (`state: "ringing"`). |
| `callStarted` | `OperatorCall` | L'audio è stabilito (dopo `accept` / `dial`). |
| `callAnswered` | `OperatorCall` | Il chiamato ha **risposto** (la conversazione è iniziata). Sulle chiamate in uscita `callStarted` indica solo che il leg audio è aperto — il destinatario può ancora stare squillando: usa `callAnswered` per far partire i timer. Sulle inbound segue immediatamente `callStarted`. |
| `callEnded` | `OperatorCall` | Una chiamata è terminata (ispeziona `endReason`). |
| `error` | `OperatorError` | Un errore non fatale; l'SDK continua a funzionare dove può. |

## `OperatorCall`

Handle a una singola chiamata, ottenuto dagli eventi `incomingCall` /
`callStarted` o restituito da `dial`.

```ts
interface OperatorCall {
  readonly callSid: string;
  readonly direction: "inbound" | "outbound";
  readonly from?: string;          // numero controparte (E.164), quando noto
  readonly to?: string;            // numero locale/chiamato (E.164), quando noto
  readonly state: "ringing" | "connecting" | "active" | "ended";
  readonly endReason?: CallEndReason; // valorizzato quando state === "ended"
  readonly answered: boolean;      // true da quando il chiamato ha risposto
  readonly answeredAt?: Date;      // istante della risposta (vedi callAnswered)
  readonly muted: boolean;

  accept(): void;               // risponde a un'offerta in entrata (no-op se non ringing)
  reject(): void;               // rifiuta un'offerta in entrata (no-op se non ringing)
  mute(on: boolean): void;      // silenzia/riattiva il microfono dell'operatore
  sendDtmf(digit: string): void; // "0"-"9", "*", "#" — vedi nota
  hangup(): void;               // termina la chiamata
}
```

| Proprietà / metodo | Tipo | Note |
|---|---|---|
| `callSid` | `string` | Identificatore della chiamata sulla piattaforma. |
| `direction` | `CallDirection` | `"inbound"` o `"outbound"`. |
| `from` | `string \| undefined` | Numero della controparte (E.164), quando noto. |
| `to` | `string \| undefined` | Numero locale/chiamato (E.164), quando noto. |
| `state` | `CallState` | Stato corrente del ciclo di vita. |
| `endReason` | `CallEndReason \| undefined` | Valorizzato una volta che `state === "ended"`. |
| `answered` | `boolean` | `true` da quando la conversazione è iniziata (outbound: il chiamato ha risposto; inbound: audio attivo). Distingue "squillo" da "conversazione". |
| `answeredAt` | `Date \| undefined` | Istante della risposta — utile per calcolare la durata reale della conversazione. |
| `muted` | `boolean` | Se il microfono è attualmente silenziato. |
| `accept()` | `void` | Risponde a un'offerta in entrata. No-op se non in `ringing`. |
| `reject()` | `void` | Rifiuta un'offerta in entrata. No-op se non in `ringing`. |
| `mute(on)` | `void` | Silenzia (`true`) o riattiva (`false`) il microfono. |
| `sendDtmf(digit)` | `void` | Invia un tono DTMF — vedi nota sotto. |
| `hangup()` | `void` | Termina la chiamata. |

<Callout type="info">
  **`sendDtmf` inoltra la cifra alla rete telefonica.** La cifra è validata,
  emessa come messaggio di controllo e il server inietta il corrispondente tono
  DTMF in-band sulla tratta telefonica: la controparte (es. un IVR) lo sente.
  Durante l'iniezione del tono (~260ms per cifra, cumulativi su cifre rapide)
  il microfono dell'operatore verso la controparte è brevemente soppresso, così
  la voce non corrompe il tono. Nota: l'operatore **non** sente il proprio
  tono — il feedback locale alla pressione dei tasti è a carico della tua UI.
</Callout>

## Tipi

### `OperatorPhoneNumber`

```ts
interface OperatorPhoneNumber {
  id: string;                 // passa a goOnline([...])
  phoneNumber: string;        // E.164 — usa come callerId in dial
  displayName: string | null; // etichetta leggibile, quando impostata
}
```

### `CallDirection`

```ts
type CallDirection = "inbound" | "outbound";
```

### `CallState`

```ts
type CallState =
  | "ringing"    // offerta in entrata ricevuta, non ancora accettata
  | "connecting" // accettata / composta, bridge audio in apertura
  | "active"     // audio in transito
  | "ended";     // terminata
```

### `CallEndReason`

```ts
type CallEndReason =
  | "hangup"         // l'operatore locale ha riagganciato
  | "remote_hangup"  // la controparte ha riagganciato / la piattaforma ha chiuso la chiamata
  | "taken_by_other" // un'offerta in entrata accettata da un altro operatore
  | "rejected"       // l'operatore locale ha rifiutato l'offerta in entrata
  | "no_answer"      // nessuna risposta in tempo (offerta in entrata o outbound non risposto)
  | "failed"         // un errore ha impedito di connettere la chiamata (incl. occupato)
  | "offline";       // la sessione è andata offline mentre la chiamata era attiva
```

### `PresenceState`

```ts
type PresenceState = "offline" | "connecting" | "online" | "reconnecting";
```

### `DialOptions`

```ts
interface DialOptions {
  // Caller ID da presentare — DEVE essere un numero del tuo account, attivo.
  callerId: string;
}
```

### `OperatorError`

Payload dell'evento `error` (e forma di `OperatorRequestError`).

```ts
interface OperatorError {
  code: string;     // codice macchina stabile, es. "MIC_PERMISSION_DENIED", "WS_ERROR"
  message: string;  // descrizione leggibile
  cause?: unknown;  // errore originale / payload del server, se presente
}
```

I codici che incontrerai più spesso: `MIC_PERMISSION_DENIED`, `WS_ERROR`,
`UNAUTHORIZED`, `REQUEST_FAILED`. La pagina
[Troubleshooting](/docs/operator-sdk/troubleshooting) li approfondisce.

## Vedi anche

<Cards>
  <Card href="/docs/operator-sdk/numeri-presenza" title="Numeri & presenza" description="listPhoneNumbers, goOnline / goOffline, availabilityChanged." />
  <Card href="/docs/operator-sdk/chiamate-in-entrata" title="Chiamate in entrata" description="incomingCall, accept / reject, endReason." />
  <Card href="/docs/operator-sdk/chiamate-in-uscita" title="Chiamate in uscita" description="dial, DialOptions, stati della chiamata." />
  <Card href="/docs/operator-sdk/audio-microfono" title="Audio & microfono" description="audioConstraints, setAudioConstraints, mute, sendDtmf." />
</Cards>