Protocollo WebSocket AudioBridge

Configurazione del Bridge

Nella sezione Bridge del portale apri Nuovo Bridge e compila i parametri necessari all'attivazione. Il modulo è suddiviso in sezioni:

1. Connessione WebSocket — inserisci il Dominio WebSocket (es. bridge.example.com) e l'Endpoint opzionale (es. /websocket): il portale compone da solo l'URL finale wss://…. Scegli il Transport (es. binary) e, se vuoi aggregare l'audio uplink in frame di durata fissa, la wsFrameDuration in ms, fino a un massimo di 200 (se lasciata vuota, ogni frame viene inviato appena disponibile).
2. Bearer auth token — inserisci il token con cui il tuo server ci autentica: lo invieremo nell'header Authorization: Bearer a ogni connessione.
3. Identità bridge — assegna un Nome e una Descrizione al bridge; servono esclusivamente a identificarlo nel portale.
4. Riconoscimento DTMF — imposta minLength, maxLength e timeout (ms) per l'aggregazione delle cifre digitate in chiamata (vedi sezione DTMF).
5. (Opzionale) Custom parameters — aggiungi coppie chiave/valore (con relativo Tipo) che riceverai nel campo customParameters dell'evento start di ogni chiamata.
6. Premi Salva: il bridge è configurato e le chiamate in arrivo vengono instradate verso la tua WebSocket.

audiobridge.beevoip.it · Nuovo Bridge Audio

Collegamento alla linea telefonica

Perché le chiamate raggiungano il tuo bridge sono necessarie una o più numerazioni telefoniche. Hai due opzioni:

• Ottieni un numero BEEVOIP — richiedi una numerazione sulla nostra rete, direttamente dal portale.
• Collega il tuo centralino (BYOC) — porti le tue numerazioni e instradi le chiamate dal tuo centralino verso AudioBridge.

Ottenere un numero BEEVOIP

Nel portale vai in Numeri Beevoip › Gestione Numeri e premi Richiedi numero.

Per l'evasione della richiesta sono necessari i seguenti documenti:

• un documento d'identità;
• una visura camerale;
• un'utenza aziendale in cui siano visibili il nome dell'azienda e l'indirizzo (es. una bolletta o un contratto telefonico).

audiobridge.beevoip.it · Numeri Beevoip › Gestione Numeri

Collegare il tuo centralino (BYOC)

Se hai già le tue numerazioni su un centralino, vai nella sezione BYOC. In IP sorgenti autorizzati aggiungi una riga con:

• l'IP sorgente del tuo centralino;
• una descrizione per identificarlo;
• il Bridge a cui collegare le chiamate che arrivano da quell'IP.

Dopo il salvataggio, le chiamate provenienti da quell'IP vengono instradate al bridge selezionato.

audiobridge.beevoip.it · BYOC › IP Sorgenti

Connessione & sicurezza

AudioBridge apre la WebSocket verso l'endpoint configurato nel portale (es. wss://host/audio).

• TLS — obbligatorio: l'URL è sempre wss:// e la connessione è cifrata. Il tuo server deve esporre un certificato TLS valido.
• Token — statico e obbligatorio: lo definisce il tuo server e lo inserisci nel portale BEEVOIP; AudioBridge lo invia nell'header Authorization a ogni connessione per autenticarsi verso il tuo server.
• Indirizzi sorgente — le connessioni di AudioBridge provengono dalla subnet 20.47.65.96/28: abilitala sul tuo firewall.

Formato audio

• Sample rate 8000 Hz, mono, 1 byte/sample.
• Codec: A-law di default (sulle nostre numerazioni). Su SIP trunk è possibile negoziare A-law o µ-law.
• PCMA → audio/x-alaw, PCMU → audio/x-mulaw.
• L'audio è costituito dai soli byte del codec, senza alcun header: trasmessi come tali in binary, codificati in base64 in json.

Framing

L'uplink viene aggregato in frame da wsFrameDuration ms (default 20, massimo 200: valori superiori vengono ridotti a 200; a 8 kHz A-law, 20 ms corrispondono a 160 byte). I frame di downlink possono avere qualsiasi dimensione: AudioBridge esegue il re-framing verso la rete telefonica.

Trasporto: binary o json

La modalità si seleziona per chiamata ed è indicata nel campo start.transport. I messaggi di controllo sono sempre JSON in entrambe le modalità: cambia esclusivamente il trasporto dell'audio.

Il campo sequenceNumber è presente solo in modalità json.

Ciclo di vita della chiamata

1. Apertura WebSocket — alla risposta della chiamata, AudioBridge apre la connessione verso il tuo endpoint wss:// inviando il token nell'header Authorization: Bearer. Il tuo server lo verifica e accetta la connessione.
2. connected — solo in modalità json: primo messaggio dopo l'apertura, conferma la connessione e comunica la versione del protocollo. In binary questo evento non viene inviato.
3. start — il messaggio di handshake: contiene sessionId, numeri chiamante e chiamato, mediaFormat, transport e i customParameters configurati nel portale. Fornisce tutti i metadati necessari a gestire la chiamata.
4. Audio uplink — la voce del chiamante viene trasmessa al tuo servizio: frame WebSocket binari in binary, eventi media con payload base64 in json. Lo streaming inizia immediatamente dopo l'evento start.
5. Audio downlink — in parallelo (full-duplex), il tuo servizio invia l'audio da riprodurre al chiamante, nel formato previsto dal trasporto selezionato.
6. clear (opzionale) — se il chiamante inizia a parlare durante la riproduzione di un prompt, il tuo servizio invia clear per svuotare il buffer di riproduzione (barge-in) e interrompere immediatamente l'audio in corso.
7. stop — al termine della chiamata, AudioBridge invia l'evento stop con la reason (es. hangup): dopo questo evento non viene più trasmesso audio.
8. Chiusura WebSocket — AudioBridge chiude la connessione con codice 1000 (chiusura normale). Successivamente riceverai il webhook di fine chiamata, se configurato.

Messaggi in uscita (AudioBridge → tuo servizio)

connected

Primo messaggio dopo l'apertura della WebSocket, solo in modalità json: conferma la connessione e comunica la versione del protocollo. In binary non viene inviato.

{ "event": "connected", "version": "1.0.0" }

start

Messaggio di handshake con i metadati di sessione e il formato audio. I numeri chiamante e chiamato sono espressi in formato E.164 (sulle nostre numerazioni). In modalità json il messaggio include anche "sequenceNumber": "1"; in binary (come nell'esempio) il campo è omesso.

{
  "event": "start",
  "start": {
    "sessionId": "1c2f...-call-uuid",
    "callerNumber": "+390612345678",
    "recipientNumber": "+390699999999",
    "mediaFormat": { "encoding": "audio/x-alaw", "sampleRate": 8000, "channels": 1 },
    "transport": "binary",
    "customParameters": { "cliente": "acme" }
  }
}

media (uplink, solo json)

In modalità binary l'uplink è trasmesso direttamente come frame WebSocket binari: questo messaggio non viene inviato.

{ "event": "media", "sequenceNumber": "42",
  "media": { "track": "inbound", "chunk": "41", "timestamp": "820", "payload": "<base64>" } }

Altri eventi

Messaggi in entrata (tuo servizio → AudioBridge)

Audio downlink

• binary: frame WebSocket binari, riprodotti al chiamante senza alcuna trasformazione.
• json: evento media con track: "outbound" e payload base64.

{ "event": "media", "media": { "track": "outbound", "payload": "<base64>" } }

clear (barge-in)

Svuota il buffer di riproduzione: consente di interrompere un prompt in corso quando il chiamante inizia a parlare.

{ "event": "clear" }

mark

Posiziona un marcatore nello stream di riproduzione; AudioBridge risponde con un evento mark in uscita quando la riproduzione raggiunge quel punto. Se un clear svuota il buffer prima che il punto marcato venga raggiunto, i mark in coda vengono comunque confermati subito: l'eco non distingue tra audio riprodotto e audio scartato dal clear (stessa semantica di Twilio Media Streams).

{ "event": "mark", "mark": { "name": "prompt-1" } }

L'eco in uscita ha lo stesso formato, con lo stesso name (e il sequenceNumber in modalità json):

{ "event": "mark", "sequenceNumber": "60", "mark": { "name": "prompt-1" } }

DTMF

L'evento dtmf viene generato a ogni cifra digitata dal chiamante. La modalità di ricezione si configura nel portale, nella sezione Riconoscimento DTMF della configurazione del Bridge. Puoi riceverlo in due modalità:

• Per cifra — un evento per ogni cifra digitata:

  { "event": "dtmf", "dtmf": { "digits": "5" } }

• Aggregato per lunghezza/timeout — con minLength, maxLength e timeout: un unico evento quando il numero di cifre rientra nell'intervallo configurato e il timeout scade.

Trasferimento di chiamata

Il tuo servizio cede il controllo della chiamata inviando sulla WebSocket il comando redirect. Il campo method seleziona come la chiamata viene consegnata alla destinazione indicata in extension:

{ "event": "redirect", "extension": "xxx", "method": "refer" }

method: "refer" (predefinito)

AudioBridge rilascia la chiamata al trunk SIP da cui proviene, indicando come destinazione l'interno specificato: è quindi il tuo centralino a instradare la chiamata verso quell'interno. Poiché il trasferimento è delegato al peer SIP, questa modalità è utilizzabile solo quando AudioBridge è attestato su trunk (scenario BYOC): sulle numerazioni Beevoip non esiste un centralino a cui rilasciare la chiamata. La destinazione è un interno del trunk, non un numero della rete pubblica, e il trasferimento non genera traffico tariffato.

method: "forward"

AudioBridge instrada la chiamata in uscita sulla rete pubblica verso il numero indicato: la destinazione può essere esclusivamente una numerazione mobile e può essere fatto esclusivamente sulle chiamate in inbound con numerazioni BEEVOIP. La gamba in uscita è a tutti gli effetti una chiamata in uscita e viene tariffata come traffico outbound, secondo il piano tariffario applicato alla destinazione.

Fine chiamata & webhook

Al termine della chiamata AudioBridge invia una richiesta POST all'endpoint che hai configurato, con body application/json:

{
  "sessionId": "1c2f...-call-uuid",
  "durationSecs": 128,
  "reason": "hangup"
}

sessionId coincide con quello dell'evento start; reason riporta la causale dell'evento stop, utile per la rendicontazione.

Registrazione

AudioBridge non conserva l'audio delle chiamate. Poiché il tuo servizio riceve l'intero flusso full-duplex sulla WebSocket, puoi registrare la conversazione lato tuo (i frame sono A-law a 8 kHz).

Keep-alive & chiusura

• AudioBridge invia un ping a intervalli regolari di pingIntervalMs; qualora il pong di risposta non pervenga entro pongTimeoutMs, la connessione viene considerata inattiva e viene chiusa. Le implementazioni WebSocket conformi allo standard rispondono ai ping in modo automatico, senza necessità di interventi da parte del tuo servizio.
• In fase di chiusura, AudioBridge trasmette dapprima l'evento stop, contenente il motivo della terminazione, e successivamente effettua la chiusura della WebSocket con codice 1000. Il motivo è riportato esclusivamente nell'evento stop e non nel codice di chiusura.

Fatturazione

• In entrata e streaming — tariffazione al minuto, anticipata.
• In uscita (incluso il trasferimento verso numerazioni esterne) — tariffazione al minuto, anticipata.

Il listino completo è disponibile sulla pagina prezzi.