Protocole WebSocket AudioBridge

Configuration du Bridge

Dans la section Bridge du portail, ouvrez Nouveau Bridge et renseignez les paramètres nécessaires à l'activation. Le formulaire est découpé en sections :

1. Connexion WebSocket — saisissez le Domaine WebSocket (ex. bridge.example.com) et l'Endpoint optionnel (ex. /websocket) : le portail compose lui-même l'URL final wss://…. Choisissez le Transport (ex. binary) et, si vous voulez agréger l'audio uplink en frames de durée fixe, la wsFrameDuration en ms, jusqu'à un maximum de 200 (si le champ reste vide, chaque frame est envoyé dès qu'il est disponible).
2. Bearer auth token — saisissez le token avec lequel votre serveur nous authentifie : nous l'enverrons dans l'header Authorization: Bearer à chaque connexion.
3. Identité du bridge — attribuez un Nom et une Description au bridge ; ils servent uniquement à l'identifier dans le portail.
4. Reconnaissance DTMF — définissez minLength, maxLength et timeout (ms) pour l'agrégation des chiffres saisis en appel (voir la section DTMF).
5. (Optionnel) Custom parameters — ajoutez des paires clé/valeur (avec leur Type) que vous recevrez dans le champ customParameters de l'événement start de chaque appel.
6. Cliquez sur Enregistrer : le bridge est configuré et les appels entrants sont routés vers votre WebSocket.

audiobridge.beevoip.it · Nouveau Bridge Audio

Raccordement à la ligne téléphonique

Pour que les appels atteignent votre bridge, un ou plusieurs numéros de téléphone sont nécessaires. Deux options :

• Obtenez un numéro BEEVOIP — demandez un numéro sur notre réseau, directement depuis le portail.
• Raccordez votre standard (BYOC) — vous apportez vos numéros et routez les appels de votre standard vers AudioBridge.

Obtenir un numéro BEEVOIP

Dans le portail, allez dans Numéros Beevoip › Gestion des numéros et cliquez sur Demander un numéro.

Le traitement de la demande nécessite les documents suivants :

• une pièce d'identité ;
• un extrait du registre des sociétés (visura camerale) ;
• une facture d'entreprise où figurent le nom de la société et l'adresse (ex. une facture ou un contrat téléphonique).

audiobridge.beevoip.it · Numéros Beevoip › Gestion des numéros

Raccorder votre standard (BYOC)

Si vous avez déjà vos numéros sur un standard, allez dans la section BYOC. Dans IP sources autorisées, ajoutez une ligne avec :

• l'IP source de votre standard ;
• une description pour l'identifier ;
• le Bridge auquel raccorder les appels provenant de cette IP.

Après l'enregistrement, les appels provenant de cette IP sont routés vers le bridge sélectionné.

audiobridge.beevoip.it · BYOC › IP Sources

Connexion & sécurité

AudioBridge ouvre la WebSocket vers l'endpoint configuré dans le portail (ex. wss://host/audio).

• TLS — obligatoire : l'URL est toujours wss:// et la connexion est chiffrée. Votre serveur doit exposer un certificat TLS valide.
• Token — statique et obligatoire : c'est votre serveur qui le définit et vous le saisissez dans le portail BEEVOIP ; AudioBridge l'envoie dans l'header Authorization à chaque connexion pour s'authentifier auprès de votre serveur.
• Adresses sources — les connexions d'AudioBridge proviennent du sous-réseau 20.47.65.96/28 : autorisez-le sur votre firewall.

Format audio

• Fréquence d'échantillonnage 8000 Hz, mono, 1 byte/sample.
• Codec : A-law par défaut (sur nos numéros). Sur trunk SIP, A-law ou µ-law se négocient.
• PCMA → audio/x-alaw, PCMU → audio/x-mulaw.
• L'audio est constitué des seuls bytes du codec, sans aucun header : transmis tels quels en binary, encodés en base64 en json.

Framing

L'uplink est agrégé en frames de wsFrameDuration ms (défaut 20, maximum 200 : les valeurs supérieures sont ramenées à 200 ; à 8 kHz en A-law, 20 ms correspondent à 160 bytes). Les frames de downlink peuvent avoir n'importe quelle taille : AudioBridge effectue le re-framing vers le réseau téléphonique.

Transport : binary ou json

Le mode se sélectionne par appel et est indiqué dans le champ start.transport. Les messages de contrôle sont toujours JSON dans les deux modes : seul le transport de l'audio change.

Le champ sequenceNumber n'est présent qu'en mode json.

Cycle de vie de l'appel

1. Ouverture de la WebSocket — à la réponse de l'appel, AudioBridge ouvre la connexion vers votre endpoint wss:// en envoyant le token dans l'header Authorization: Bearer. Votre serveur le vérifie et accepte la connexion.
2. connected — uniquement en mode json : premier message après l'ouverture, il confirme la connexion et communique la version du protocole. En binary, cet événement n'est pas envoyé.
3. start — le message de handshake : il contient sessionId, les numéros appelant et appelé, mediaFormat, transport et les customParameters configurés dans le portail. Il fournit toutes les métadonnées nécessaires pour gérer l'appel.
4. Audio uplink — la voix de l'appelant est transmise à votre service : frames WebSocket binaires en binary, événements media avec payload base64 en json. Le streaming démarre immédiatement après l'événement start.
5. Audio downlink — en parallèle (full-duplex), votre service envoie l'audio à rejouer à l'appelant, dans le format prévu par le transport sélectionné.
6. clear (optionnel) — si l'appelant commence à parler pendant la lecture d'un prompt, votre service envoie clear pour vider le buffer de lecture (barge-in) et interrompre immédiatement l'audio en cours.
7. stop — à la fin de l'appel, AudioBridge envoie l'événement stop avec la reason (ex. hangup) : après cet événement, plus aucun audio n'est transmis.
8. Fermeture de la WebSocket — AudioBridge ferme la connexion avec le code 1000 (fermeture normale). Vous recevrez ensuite le webhook de fin d'appel, s'il est configuré.

Messages sortants (AudioBridge → votre service)

connected

Premier message après l'ouverture de la WebSocket, uniquement en mode json : il confirme la connexion et communique la version du protocole. En binary, il n'est pas envoyé.

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

start

Message de handshake avec les métadonnées de session et le format audio. Les numéros appelant et appelé sont exprimés au format E.164 (sur nos numéros). En mode json, le message inclut aussi "sequenceNumber": "1" ; en binary (comme dans l'exemple), le champ est omis.

{
  "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, json uniquement)

En mode binary, l'uplink est transmis directement en frames WebSocket binaires : ce message n'est pas envoyé.

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

Autres événements

Messages entrants (votre service → AudioBridge)

Audio downlink

• binary : frames WebSocket binaires, joués à l'appelant sans aucune transformation.
• json : événement media avec track: "outbound" et payload base64.

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

clear (barge-in)

Vide le buffer de lecture : permet d'interrompre un prompt en cours quand l'appelant commence à parler.

{ "event": "clear" }

mark

Place un marqueur dans le stream de lecture ; AudioBridge répond avec un événement mark sortant quand la lecture atteint ce point. Si un clear vide le buffer avant que le point marqué soit atteint, les mark en file sont tout de même confirmés immédiatement : l'écho ne distingue pas l'audio joué de l'audio écarté par le clear (même sémantique que Twilio Media Streams).

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

L'écho sortant a le même format, avec le même name (et le sequenceNumber en mode json) :

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

DTMF

L'événement dtmf est généré à chaque chiffre saisi par l'appelant. Le mode de réception se configure dans le portail, dans la section Reconnaissance DTMF de la configuration du Bridge. Deux modes de réception :

• Par chiffre — un événement pour chaque chiffre saisi :

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

• Agrégé par longueur/timeout — avec minLength, maxLength et timeout : un seul événement quand le nombre de chiffres entre dans l'intervalle configuré et que le timeout expire.

Transfert d'appel

Votre service cède le contrôle de l'appel en envoyant sur la WebSocket la commande redirect. Le champ method sélectionne comment l'appel est remis à la destination indiquée dans extension :

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

method: "refer" (par défaut)

AudioBridge relâche l'appel vers le trunk SIP d'origine, en indiquant comme destination le poste spécifié : c'est donc votre standard qui route l'appel vers ce poste. Le transfert étant délégué au peer SIP, ce mode n'est utilisable que lorsque AudioBridge est raccordé sur trunk (scénario BYOC) : sur les numéros Beevoip, il n'existe pas de standard auquel relâcher l'appel. La destination est un poste du trunk, pas un numéro du réseau public, et le transfert ne génère pas de trafic facturé.

method: "forward"

AudioBridge route l'appel en sortie sur le réseau public vers le numéro indiqué : la destination peut être exclusivement un numéro mobile et ce mode s'applique exclusivement aux appels inbound sur numéros BEEVOIP. La jambe sortante est à tous égards un appel sortant et est facturée comme du trafic outbound, selon la grille tarifaire appliquée à la destination.

Fin d'appel & webhook

À la fin de l'appel, AudioBridge envoie une requête POST à l'endpoint que vous avez configuré, avec un body application/json :

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

sessionId coïncide avec celui de l'événement start ; reason reprend la cause de l'événement stop, utile pour le reporting.

Enregistrement

AudioBridge ne conserve pas l'audio des appels. Votre service recevant l'intégralité du flux full-duplex sur la WebSocket, vous pouvez enregistrer la conversation de votre côté (les frames sont en A-law à 8 kHz).

Keep-alive & fermeture

• AudioBridge envoie un ping à intervalles réguliers de pingIntervalMs ; si le pong de réponse n'arrive pas dans pongTimeoutMs, la connexion est considérée inactive et fermée. Les implémentations WebSocket conformes au standard répondent aux ping automatiquement, sans intervention de votre service.
• En phase de fermeture, AudioBridge transmet d'abord l'événement stop, contenant le motif de la terminaison, puis ferme la WebSocket avec le code 1000. Le motif figure exclusivement dans l'événement stop, pas dans le code de fermeture.

Facturation

• Entrant et streaming — tarification à la minute, prépayée.
• Sortant (y compris le transfert vers des numéros externes) — tarification à la seconde.

La grille complète est disponible sur la page tarifs.