Documentación · Beta

Protocolo WebSocket AudioBridge

AudioBridge es un puente de audio full-duplex sobre WebSocket. En cada llamada la centralita abre una conexión hacia tu servicio, te transmite la voz del llamante uplink y reproduce al llamante el audio que le envías downlink.

El formato de los mensajes tiene una estructura muy similar a Twilio Media Streams (campo de evento + objeto anidado), con dos extensiones: transporte de audio binario opcional y códec A-law además de µ-law. Una integración Media Streams existente se migra a AudioBridge sustituyendo el endpoint de la WebSocket: es extremadamente sencillo y rápido.

Beta. El protocolo evoluciona solo con cambios retrocompatibles: nuevos campos y eventos opcionales, nunca modificaciones ni eliminaciones de los existentes. Las integraciones ya desarrolladas siguen funcionando sin intervención.

Configuración del Bridge

En la sección Bridge del portal abre Nuevo Bridge y rellena los parámetros necesarios para la activación. El formulario está dividido en secciones:

Conexión WebSocket — introduce el Dominio WebSocket (p. ej. bridge.example.com) y el Endpoint opcional (p. ej. /websocket): el portal compone por sí solo la URL final wss://…. Elige el Transport (p. ej. binary) y, si quieres agregar el audio uplink en frames de duración fija, la wsFrameDuration en ms, hasta un máximo de 200 (si se deja vacía, cada frame se envía en cuanto está disponible).
Bearer auth token — introduce el token con el que tu servidor nos autentica: lo enviaremos en la cabecera Authorization: Bearer en cada conexión.
Identidad del bridge — asigna un Nombre y una Descripción al bridge; sirven exclusivamente para identificarlo en el portal.
Reconocimiento DTMF — configura minLength, maxLength y timeout (ms) para la agregación de las cifras marcadas durante la llamada (ver sección DTMF).
(Opcional) Custom parameters — añade pares clave/valor (con su Tipo) que recibirás en el campo customParameters del evento start de cada llamada.
Pulsa Guardar: el bridge queda configurado y las llamadas entrantes se enrutan hacia tu WebSocket.

Formulario del portal para crear un Bridge de Audio: secciones Conexión WebSocket (dominio, endpoint, bearer token, transport, URL final), Identidad del bridge (nombre y descripción), Reconocimiento DTMF (minLength, maxLength, timeout) y Custom parameters. — La configuración de un Bridge de Audio en el portal

Conexión a la línea telefónica

Para que las llamadas lleguen a tu bridge se necesitan una o más numeraciones telefónicas. Tienes dos opciones:

Obtén un número BEEVOIP — solicita una numeración en nuestra red, directamente desde el portal.
Conecta tu centralita (BYOC) — traes tus numeraciones y enrutas las llamadas desde tu centralita hacia AudioBridge.

Obtener un número BEEVOIP

En el portal ve a Números Beevoip › Gestión de Números y pulsa Solicitar número.

Para tramitar la solicitud se necesitan los siguientes documentos:

un documento de identidad;
un certificado de registro mercantil;
una factura de suministro de la empresa en la que sean visibles el nombre de la empresa y la dirección (p. ej. una factura o un contrato telefónico).

Sección Gestión de Números del portal: botón Solicitar número arriba a la derecha, pestañas Gestión de Números y Routing, contadores Números activos, Solicitudes abiertas y Solicitudes totales. — Números Beevoip › Gestión de Números: desde aquí solicitas una nueva numeración con «Solicitar número».

Conectar tu centralita (BYOC)

Si ya tienes tus numeraciones en una centralita, ve a la sección BYOC. En IP de origen autorizadas añade una fila con:

la IP de origen de tu centralita;
una descripción para identificarla;
el Bridge al que conectar las llamadas que llegan desde esa IP.

Tras guardar, las llamadas procedentes de esa IP se enrutan al bridge seleccionado.

Sección BYOC · IP de Origen del portal: fila con los campos IP de origen, Descripción y Bridge, con los botones Añadir IP de origen y Guardar. — BYOC › IP de origen autorizadas: asocia la IP de tu centralita a un bridge.

Conexión & seguridad

AudioBridge abre la WebSocket hacia el endpoint configurado en el portal (p. ej. wss://host/audio).

TLS — obligatorio: la URL es siempre wss:// y la conexión va cifrada. Tu servidor debe exponer un certificado TLS válido.
Token — estático y obligatorio: lo define tu servidor y lo introduces en el portal BEEVOIP; AudioBridge lo envía en la cabecera Authorization en cada conexión para autenticarse ante tu servidor.
Direcciones de origen — las conexiones de AudioBridge proceden de la subnet 20.47.65.96/28: habilítala en tu firewall.

Formato de audio

Sample rate 8000 Hz, mono, 1 byte/sample.
Códec: A-law por defecto (en nuestras numeraciones). En SIP trunk es posible negociar A-law o µ-law.
PCMA → audio/x-alaw, PCMU → audio/x-mulaw.
El audio está formado únicamente por los bytes del códec, sin ninguna cabecera: transmitidos tal cual en binary, codificados en base64 en json.

¿Migras desde Twilio? El default de Twilio Media Streams es µ-law (PCMU). En nuestras numeraciones el default es A-law: verifica qué decoder utiliza tu servidor, o negocia µ-law en el trunk.

Framing

El uplink se agrega en frames de wsFrameDuration ms (default 20, máximo 200: los valores superiores se reducen a 200; a 8 kHz A-law, 20 ms corresponden a 160 bytes). Los frames de downlink pueden tener cualquier tamaño: AudioBridge realiza el re-framing hacia la red telefónica.

Transporte: binary o json

La modalidad se selecciona por llamada y se indica en el campo start.transport. Los mensajes de control son siempre JSON en ambas modalidades: solo cambia el transporte del audio.

Modalidad	Audio	Control
binary	frames WebSocket binarios = bytes crudos del códec	mensajes JSON (text frame)
json	evento `media` con payload base64	mensajes JSON (text frame)

El campo sequenceNumber solo está presente en modalidad json.

Ciclo de vida de la llamada

connectedstartmedia ⇄dtmfmarkclearstop

Apertura de la WebSocket — al responderse la llamada, AudioBridge abre la conexión hacia tu endpoint wss:// enviando el token en la cabecera Authorization: Bearer. Tu servidor lo verifica y acepta la conexión.
connected — solo en modalidad json: primer mensaje tras la apertura, confirma la conexión y comunica la versión del protocolo. En binary este evento no se envía.
start — el mensaje de handshake: contiene sessionId, números llamante y llamado, mediaFormat, transport y los customParameters configurados en el portal. Proporciona todos los metadatos necesarios para gestionar la llamada.
Audio uplink — la voz del llamante se transmite a tu servicio: frames WebSocket binarios en binary, eventos media con payload base64 en json. El streaming empieza inmediatamente después del evento start.
Audio downlink — en paralelo (full-duplex), tu servicio envía el audio que se reproduce al llamante, en el formato previsto por el transporte seleccionado.
clear (opcional) — si el llamante empieza a hablar durante la reproducción de un prompt, tu servicio envía clear para vaciar el buffer de reproducción (barge-in) e interrumpir de inmediato el audio en curso.
stop — al terminar la llamada, AudioBridge envía el evento stop con la reason (p. ej. hangup): después de este evento no se transmite más audio.
Cierre de la WebSocket — AudioBridge cierra la conexión con código 1000 (cierre normal). Después recibirás el webhook de fin de llamada, si está configurado.

Mensajes salientes (AudioBridge → tu servicio)

connected

Primer mensaje tras la apertura de la WebSocket, solo en modalidad json: confirma la conexión y comunica la versión del protocolo. En binary no se envía.

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

start

Mensaje de handshake con los metadatos de sesión y el formato de audio. Los números llamante y llamado se expresan en formato E.164 (en nuestras numeraciones). En modalidad json el mensaje incluye además "sequenceNumber": "1"; en binary (como en el ejemplo) el campo se omite.

{
  "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)

En modalidad binary el uplink se transmite directamente como frames WebSocket binarios: este mensaje no se envía.

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

Otros eventos

Evento	Descripción
dtmf	cifra marcada por el llamante (ver sección DTMF)
mark	confirmación de un `mark` recibido, emitida cuando el punto marcado se ha reproducido (o de inmediato, si un `clear` ha descartado el audio en cola)
stop	enviado antes del cierre de la WebSocket: `{ "stop": { "reason": "hangup" } }`
error	`{ "error": { "code": "...", "message": "..." } }`

Mensajes entrantes (tu servicio → AudioBridge)

Audio downlink

binary: frames WebSocket binarios, reproducidos al llamante sin ninguna transformación.
json: evento media con track: "outbound" y payload base64.

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

clear (barge-in)

Vacía el buffer de reproducción: permite interrumpir un prompt en curso cuando el llamante empieza a hablar.

{ "event": "clear" }

mark

Coloca un marcador en el stream de reproducción; AudioBridge responde con un evento mark saliente cuando la reproducción alcanza ese punto. Si un clear vacía el buffer antes de que el punto marcado se alcance, los mark en cola se confirman igualmente de inmediato: el eco no distingue entre audio reproducido y audio descartado por el clear (misma semántica que Twilio Media Streams).

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

El eco saliente tiene el mismo formato, con el mismo name (y el sequenceNumber en modalidad json):

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

DTMF

El evento dtmf se genera con cada cifra marcada por el llamante. La modalidad de recepción se configura en el portal, en la sección Reconocimiento DTMF de la configuración del Bridge. Puedes recibirlo de dos formas:

Por cifra — un evento por cada cifra marcada:

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

Agregado por longitud/timeout — con minLength, maxLength y timeout: un único evento cuando el número de cifras entra en el intervalo configurado y el timeout vence.

Transferencia de llamada

Tu servicio cede el control de la llamada enviando por la WebSocket el comando redirect. El campo method selecciona cómo se entrega la llamada al destino indicado en extension:

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

Campo	Tipo	Descripción
extension	string, obligatorio	destino de la transferencia: la extensión a alcanzar con `refer`, el número llamado con `forward`
method	string, opcional	`"refer"` o `"forward"`. Si falta o es `undefined`, se aplica `"refer"`

method: "refer" (predeterminado)

AudioBridge libera la llamada al trunk SIP del que procede, indicando como destino la extensión especificada: es por tanto tu centralita la que enruta la llamada hacia esa extensión. Como la transferencia se delega al peer SIP, esta modalidad solo puede usarse cuando AudioBridge está conectado a un trunk (escenario BYOC): en las numeraciones Beevoip no existe una centralita a la que liberar la llamada. El destino es una extensión del trunk, no un número de la red pública, y la transferencia no genera tráfico tarificado.

method: "forward"

AudioBridge enruta la llamada en salida por la red pública hacia el número indicado: el destino puede ser exclusivamente una numeración móvil y puede hacerse exclusivamente en las llamadas inbound con numeraciones BEEVOIP. El tramo saliente es a todos los efectos una llamada saliente y se tarifica como tráfico outbound, según el plan tarifario aplicado al destino.

Fin de llamada & webhook

Al terminar la llamada AudioBridge envía una petición POST al endpoint que hayas configurado, con body application/json:

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

sessionId coincide con el del evento start; reason recoge la causa del evento stop, útil para la contabilización.

Grabación

AudioBridge no conserva el audio de las llamadas. Como tu servicio recibe el flujo full-duplex completo por la WebSocket, puedes grabar la conversación en tu lado (los frames son A-law a 8 kHz).

Keep-alive & cierre

AudioBridge envía un ping a intervalos regulares de pingIntervalMs; si el pong de respuesta no llega dentro de pongTimeoutMs, la conexión se considera inactiva y se cierra. Las implementaciones WebSocket conformes al estándar responden a los ping de forma automática, sin necesidad de intervención por parte de tu servicio.
En la fase de cierre, AudioBridge transmite primero el evento stop, con el motivo de la terminación, y después efectúa el cierre de la WebSocket con código 1000. El motivo se recoge exclusivamente en el evento stop y no en el código de cierre.

Facturación

Entrante y streaming — tarificación por minuto, prepagada.
Saliente (incluida la transferencia hacia numeraciones externas) — tarificación por segundo.

La lista de precios completa está disponible en la página de precios.