WebSockets en la Voice API de Vonage

Esta guía explica cómo los WebSockets se integran con la Voice API de Vonage y te ayudan a crear sofisticadas aplicaciones en tiempo real, como bots de voz con inteligencia artificial o servicios de transcripción en vivo.

¿Qué son los WebSockets?

Los WebSockets son un protocolo de comunicación que proporciona un conexión dúplex completa y persistente entre una aplicación y la plataforma Vonage Voice.
A diferencia de HTTP, que requiere una solicitud independiente para cada intercambio, un WebSocket mantiene una única conexión abierta a través de la cual se pueden enviar mensajes en ambas direcciones en cualquier momento.

Es ideal para situaciones que requieren flujo de datos de baja latenciacomo enviar y recibir paquetes de audio en tiempo real.

¿Por qué son importantes los WebSockets para los conectores de IA?

En las aplicaciones de voz de IA, a menudo es necesario:

Recibir audio en directo de una persona que llama.
Transcriba ese audio en directo.
Enviar respuestas de audio sintetizadas a la persona que llama.
Enviar metadatos para la sesión.
Intercambiar señales de control dinámicamente.

Los WebSockets lo permiten:

Transmisión de audio en paquetes binarios.
Intercambio de mensajes de texto como órdenes de control o eventos.
Envío de metadatos al inicio de la sesión.
Permitir una interacción casi instantánea con los servicios de IA, como los motores de reconocimiento de voz, NLU o TTS.

Configuración de un servidor WebSocket en su aplicación

Para conectar Vonage a tu servidor WebSocket (tu aplicación), debes:

Despliegue de un punto final WebSocket accesible a través de una URL segura (wss://).
Maneja las conexiones entrantes iniciadas por Vonage.
Procesar ambos mensajes binarios (audio) y mensajes de texto (comandos/eventos JSON).
Opcionalmente, implementar la lógica de autenticación o autorización.

Ejemplo (Node.js, ws):

const WebSocket = require('ws');
const server = new WebSocket.Server({ port: 8080 });

server.on('connection', socket => {
  console.log('Vonage connected');
  
  socket.on('message', message => {
    if (typeof message === 'string') {
      // Handle JSON commands or events
      console.log('Text message:', message);
    } else {
      // Handle binary audio
      console.log('Binary audio packet received');
    }
  });
  
  socket.on('close', () => {
    console.log('WebSocket disconnected');
  });
});

Uso de una OCN para establecer la conexión WebSocket

Para indicar a Vonage que transmita audio a tu servidor WebSocket, configura un NCCO (Objeto de control de llamadas Nexmo) acción de tipo connect:

Ejemplo OCN:

[
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "wss://your-server.example.com",
        "content-type": "audio/l16;rate=16000",
        "headers": {
          "custom-header": "value"
        }
      }
    ]
  }
]

Formato de audio:

El formato de audio se controla mediante content-type:
- audio/l16;rate=24000: PCM lineal de 16 bits, 24 kHz
- audio/l16;rate=16000: PCM lineal de 16 bits, 16 kHz (recomendado para el reconocimiento de voz).
- audio/l16;rate=80008kHz si es necesario.

Autenticación de la conexión WebSocket

Cuando Vonage se conecta a tu servidor WebSocket, es posible que desees verificar que la conexión entrante provenga de Vonage. Puedes hacerlo configurando un authorization en el extremo WebSocket.

Se admiten dos modos de autorización:

vonage: Vonage incluye un Authorization en el handshake de apertura WebSocket utilizando el mismo formato JWT utilizado para los webhooks firmados (Bearer <JWT>). Su servidor debe validar este JWT. Véase Webhooks firmados para obtener orientación sobre cómo validar los JWT de Vonage.
custom: Su aplicación proporciona un Authorization que Vonage enviará textualmente en el apretón de manos de apertura. Esto te permite usar tu propio esquema de autorización y credenciales.

Nota: Si authorization se omite, se establece en nullo a un objeto vacío ({}), Vonage no aplicará ningún comportamiento de autorización para el intercambio WebSocket.

Consulte los detalles en el Referencia OCNC.

Interacción bidireccional: Mensajes de audio y texto

De Vonage a su aplicación:

Mensajes binarios: Trozos de audio capturados de la persona que llama.
Mensajes de texto: Eventos JSON (por ejemplo, conexión abierta, borrada, notificaciones).

De tu Application a Vonage:

Mensajes binarios: Audio para reproducir a la persona que llama.
Mensajes de texto: Comandos para controlar la reproducción o solicitar notificaciones.

Este flujo bidireccional permite:

Transcripción en tiempo real.
Reproducción de voz sintetizada.
Control de los búferes de reproducción.
Interacciones basadas en eventos.

Análisis de paquetes de Vonage (Binario vs JSON)

Cuando su servidor WebSocket recibe un mensaje:

Si el mensaje es un Buffer o ArrayBuffer:
- Es datos de audio (PCM en bruto).
Si el mensaje es una cadena:
- Es un Mensaje de control con formato JSON.

Ejemplo de evento JSON:

{
    "event":"websocket:connected",
    "content-type":"audio/l16;rate=16000",
    "prop1": "value1",
    "prop2": "value2"
}

Inspeccione siempre el tipo de mensaje para encaminar correctamente la lógica de procesamiento.

Gestión de paquetes de audio binarios entrantes

Los mensajes binarios contienen audio PCM sin procesar capturado de la persona que llama.

Características principales:

16-bit signed little-endian PCM.
Frecuencia de muestreo definida por content-type (por ejemplo, 16.000 Hz).
Cada paquete representa un breve fragmento de audio (~20 ms).

Procesamiento típico:

Introduce el audio en un motor de reconocimiento de voz.
Buffer para reproducción posterior.
Guardar en disco para su análisis.

Envío de paquetes de audio binarios a Vonage

Para reproducir audio a la persona que llama:

Codifica tu audio como PCM sin procesar.
Coinciden con la frecuencia de muestreo y el formato especificados en la OCN.
Envía los datos de audio como mensajes binarios WebSocket.

Importante:
Vonage almacena el audio entrante para reproducirlo en orden. Esto te permite poner audio en cola sin espacios, pero requiere la administración de búfer, que se explica a continuación.

Cómo funciona el búfer de audio

Cuando envías paquetes binarios de audio:

Vonage topes internamente.
El tamaño del búfer de WebSocket es de 3072 paquetes, lo que debería ser suficiente para unos 60 segundos de audio.
La reproducción se inicia automáticamente.
Los paquetes siguientes se ponen en cola.
No se puede interrumpir la reproducción a mitad de búfer sin un comando de control.

Este diseño garantiza una reproducción uniforme sin cortes de audio.

Borrar el búfer de audio (`clear` Mando)

A detener inmediatamente reproducción de audio en búfer, envíe el clear mando.

Comando de salida (de su solicitud):

{
  "action": "clear"
}

` Efecto:

Se descarta todo el audio en cola.
La reproducción se detiene inmediatamente.

Acuse de recibo (de la plataforma Vonage):

{
  "event": "websocket:cleared"
}

Escenario de uso:
Es necesario interrumpir la reproducción para responder dinámicamente a la persona que llama (por ejemplo, tras la detección de irrupción).

Notificación de fin de audio (`notify` Mando)

Para recibir una notificación cuando el búfer de audio actual haya terminado de reproducirse, utilice la función notify mando.

Comando de salida (enviar después de una carga útil de audio que desea saber si ha terminado de reproducirse):

{
  "action": "notify",
  "payload": {
    "customKey": "customValue"
  }
}

Comportamiento:

Si se está reproduciendo audio, Vonage envía una notificación entrante a tu aplicación una vez que finaliza la reproducción.
Si no se está reproduciendo audio, la notificación entrante se devuelve a su aplicación. inmediatamente.

Notificación de entrada:

{
  "event": "websocket:notify",
  "payload": {
    "customKey": "customValue"
  }
}

Escenario de uso:
Sincronice la lógica de su aplicación (por ejemplo, inicie la grabación o reproduzca un nuevo aviso cuando termine el anterior).

Escuchar a un participante concreto en una conversación multipartita

Cuando su aplicación participa en un conversación con varios tramos de llamada, como un cliente y un agente, es posible que desee que su conexión WebSocket recibir sólo el audio de un participante concreto en lugar de todo el audio mezclado.

Esto se llama control de audio selectivoy se consigue utilizando el canHear y canSpeak propiedades de la OCNC conversation acción.

¿Por qué usar esto?

Análisis del habla: Capta sólo lo que dice el cliente, ignorando al agente.
Transcripción en tiempo real: Registre el lado del cliente para el cumplimiento.
Susurros: Enviar audio sólo al agente sin que lo oiga el cliente.

Cómo configurar la escucha selectiva

Para configurarlo:

Crear una conversación con nombre (por ejemplo "customer_support").
Conecte los tramos de llamada del cliente y del agente a la conversación.
Añade tu conexión WebSocket a la misma conversaciónespecificando canHear y canSpeak según sea necesario.

Ejemplo: WebSocket escuchando sólo al cliente

A continuación se muestra un ejemplo de NCCO en el que:

El cliente se une a la conversación.
El agente se une a la conversación.
El WebSocket se conecta pero sólo recibe el audio del cliente.

Cliente Leg NCCO:

[
  {
    "action": "conversation",
    "name": "support_room"
  }
]

Agente Leg NCCO:

[
  {
    "action": "conversation",
    "name": "support_room"
  }
]

WebSocket Leg NCCO:

[
  {
    "action": "conversation",
    "name": "support_room",
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"], // Customer leg ID
    "canSpeak": []
  }
]

Cómo funciona:

El WebSocket sólo oye el customer participante.
En no devuelve audio a la conversación (canSpeak está vacía).
Si desea inyectar audio (por ejemplo, indicaciones de AI) y reproducir el audio sólo a un participante designado, puede incluir el ID de llamada (tramo) del participante en canSpeak.
Si desea que inyecte audio (por ejemplo, indicaciones de AI) y reproduzca el audio a todos los participantes, no incluya canSpeak parámetro.

Manejo de desconexiones WebSocket y opciones de Fallback

Cuando usas WebSockets con Voice API de Vonage, no sólo dependes del WebSocket en sí para saber qué está sucediendo.
Vonage también envía devoluciones de llamada de eventos a su eventUrl webhook. Estas peticiones HTTP POST proporcionan información fidedigna sobre el estado de la llamada y permiten un comportamiento alternativo si falla la conexión WebSocket.

Esto es importante porque simplemente observando el cierre de WebSocket no te dice por qué se cerró. Necesita el webhook de eventos para determinar si la desconexión fue intencionada o causada por un error.

¿Por qué es importante?

Cuando se crean experiencias de voz de producción, especialmente las impulsadas por IA o en tiempo real, las conexiones pueden fallar de forma impredecible (por ejemplo, caídas del servidor, tiempos de espera de la red).
Para ofrecer una experiencia agradable a la persona que llama, puede implementar estrategias alternativas como reproducir un aviso, transferir a un agente humano o finalizar la llamada amablemente.

Los eventos Webhook le ofrecen un mecanismo fiable para detectar estas situaciones y actuar en consecuencia.

Cómo Vonage te notifica los eventos WebSocket

Cada vez que se produce un cambio significativo en el estado de la conexión WebSocket, Vonage envía un evento webhook a su eventUrl.

Ejemplos de estados relevantes:

unanswered: Vonage no pudo establecer la conexión WebSocket.
failed: El intento de conexión ha fallado.
disconnected: La conexión WebSocket se ha interrumpido después de establecerse.

Cada acto incluye:

En uuid, identificando la llamada.
Marcas de tiempo.
Cualquier headers que especificó en la OCNC connect acción.
Campo de estado que describe lo sucedido.

Ejemplo de carga útil de evento desconectado

Este evento se envía cuando el WebSocket se desconecta después de la conexión - ya sea debido a un error o porque su aplicación lo cerró:

{
  "from": "442079460000",
  "to": "wss://example.com/socket",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "status": "disconnected",
  "timestamp": "2020-03-31T12:00:00.000Z",
  "headers": {
    "caller-id": "447700900123"
  }
}

Cómo distinguir las desconexiones intencionadas de las involuntarias

Es importante entenderlo:

Cualquier desconexiónSi su aplicación cerró intencionadamente el WebSocket o si se cayó debido a un error, plantea un disconnected evento.
Si desea terminar intencionadamente el WebSocket sin activar un fallback, Vonage recomienda terminación del tramo de llamada a través de Voice API de Vonage en lugar de simplemente cerrar la conexión WebSocket.
- De esta forma, no disconnected webhook se envía, y puede confiar en recibir disconnected sólo para fallos involuntarios.

Gestión de conexiones fallidas durante la instalación

A veces la conexión WebSocket no puede establecerse en primer lugar (por ejemplo, si su servidor está fuera de línea).
Puede configurar su connect acción a utilizar gestión sincrónica de eventos:

Ejemplo NCCO con eventType síncrono:

[
  {
    "action": "connect",
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "wss://example.com/socket",
        "content-type": "audio/l16;rate=16000",
        "headers": {
          "caller-id": "447700900123"
        }
      }
    ]
  }
]