Ir al contenido principal
Español— Elegir un idioma
Menú

Domina los eventos de WebSocket

Lección 4 de 14 Actualizado el 29 de julio de 2026 Intermedio
En esta página
  1. Una conversación compuesta por eventos JSON
  2. Lo que envía tu aplicación
  3. Lo que envía el servidor
  4. La estructura básica de un cliente
  5. La parte delicada: las interrupciones
  6. Puntos clave

Una conversación compuesta por eventos JSON

En esencia, un intercambio de voz con el Voice Agent es simplemente un flujo de mensajes JSON que circulan en ambas direcciones a través de la conexión WebSocket. Cada mensaje incluye un campo type que indica de qué se trata. Mientras no conozcas este vocabulario, tu cliente funcionará por suerte. En cuanto lo domines, sabrás exactamente dónde intervenir para cortar una respuesta, mostrar una transcripción o recuperarte de un error.

Los eventos se dividen en dos familias, según la dirección en la que viajan. Los que tú envías dirigen la sesión; los que recibes te informan de lo que ocurre en el servidor.

Lo que envía tu aplicación

Tus mensajes salientes cubren cuatro necesidades: configurar la sesión, alimentar el búfer de audio, gestionar el historial de la conversación y controlar la generación de respuestas.

EventoPropósito
session.updateConfigura o reconfigura la sesión (voz, instrucciones, herramientas, VAD, formato de audio)
input_audio_buffer.appendEnvía un fragmento de audio codificado en base64 de forma continua mientras el usuario habla
input_audio_buffer.commitConfirma el contenido actual del búfer como mensaje del usuario; solo necesario en modo manual
input_audio_buffer.clearVacía el búfer de audio sin procesarlo
conversation.item.createAñade un elemento a la conversación: un mensaje de texto, historial anterior o el resultado de una llamada a función
conversation.item.deleteElimina un elemento de la conversación por su ID
response.createSolicita al modelo que genere una respuesta; automático en modo VAD, explícito en modo manual
response.cancelCancela una respuesta que se está generando

Dos de estos mensajes merecen una atención especial. conversation.item.create es la forma de inyectar contexto: es lo que utilizas para restaurar el historial de una llamada anterior al inicio de una nueva sesión. En cuanto a input_audio_buffer.clear, resulta útil cuando el usuario claramente no ha dicho nada que merezca la pena procesar (un carraspeo captado por un micrófono demasiado sensible) y prefieres empezar de cero con un búfer limpio en lugar de dejar que el modelo interprete ruido.

Lo que envía el servidor

El flujo entrante es más activo, ya que ofrece un comentario en tiempo real de cada paso del procesamiento.

EventoSignificado
session.createdLa sesión está abierta
session.updatedSe ha aplicado una actualización de configuración
conversation.createdLa conversación está configurada
input_audio_buffer.speech_startedEl VAD detecta que el usuario ha empezado a hablar
input_audio_buffer.speech_stoppedEl VAD detecta que el usuario ha dejado de hablar
input_audio_buffer.committedEl búfer de audio se ha confirmado, ya sea por el VAD o manualmente
response.createdSe está generando una respuesta
response.output_audio.deltaUn fragmento de audio de la respuesta, en base64
response.output_audio.doneEl audio de la respuesta está completo
response.output_audio_transcript.deltaLa transcripción de texto del audio, transmitida en flujo
response.doneLa respuesta ha terminado completamente
conversation.item.input_audio_transcription.completedLa transcripción del mensaje del usuario está disponible
response.text.deltaTexto transmitido en flujo, para respuestas que no son de voz
response.function_call_arguments.deltaLos argumentos de una llamada a función, transmitidos en flujo
response.function_call_arguments.doneLa llamada a función está completa y lista para ejecutarse
errorSe ha producido un error; la mayoría son recuperables

Este último requiere una advertencia. Recibir un evento error no significa que la sesión se haya perdido. Según la referencia de xAI, la mayoría de los errores son recuperables y la sesión permanece abierta, por lo que un cliente que cierre la conexión ante el primer error romperá una conversación que podría haber continuado. Regístralo, informa al usuario si es necesario, pero mantén el socket abierto.

La estructura básica de un cliente

En la práctica, todo se reduce a un switch sobre msg.type. Esta es la forma mínima de un cliente en JavaScript:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Envía session.update con la configuración
      break;

    case "input_audio_buffer.speech_started":
      // El usuario está hablando: detén el audio de respuesta que se está reproduciendo
      break;

    case "response.output_audio.delta":
      // Decodifica el base64 y reproduce el audio
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Ejecuta la función y envía el resultado de vuelta
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Error del Voice Agent:", msg.error);
      break;
  }
};

Cuatro ramas son suficientes para ejecutar un agente: configurar al abrir la sesión, reaccionar cuando el usuario empieza a hablar, reproducir el audio entrante y ejecutar funciones. Los demás eventos enriquecen la interfaz y pueden esperar a una segunda iteración.

La parte delicada: las interrupciones

El «barge-in», cuando el usuario empieza a hablar mientras el agente aún está respondiendo, es donde se nota una implementación descuidada. El servidor cancela la respuesta actual por su cuenta y comienza a generar una nueva a partir de lo que acaba de oír. Pero mientras el servidor ha dejado de enviar datos, tu aplicación todavía tiene varios segundos de audio ya recibido en su búfer de salida.

Si no haces nada, el usuario seguirá oyendo la frase que acaba de interrumpir mientras habla por encima, y el agente dará la impresión de no estar escuchando. Por tanto, en cuanto recibas speech_started, detén el audio que se está reproduciendo, vacía el búfer de salida para no reproducir sonido obsoleto y deja que el servidor procese la nueva entrada. Estos dos pasos requieren pocas líneas de código y marcan la diferencia entre un agente al que puedes interrumpir y uno que habla al vacío.

Puntos clave

  • Los eventos del cliente cubren la configuración, el envío de audio, la gestión de la conversación y el control de las respuestas
  • Los eventos del servidor informan de la detección de voz, fragmentos de audio, transcripciones y llamadas a funciones
  • El VAD gestiona las interrupciones (barge-in) automáticamente
  • La mayoría de los eventos error son recuperables: no cierres la conexión, gestiona el error
  • En modo manual, debes llamar explícitamente a commit y luego a response.create