API reference

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
}

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

type CallDirection = "inbound" | "outbound";

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

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

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

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

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
}