Eventos de servidor a cliente
En esta página
Los mensajes que recibes
El servidor envía numerosos eventos para mantenerte informado sobre el estado de la conversación, entregar el audio de respuesta y notificar errores. Comprender estos eventos es esencial para construir una aplicación receptiva y fiable.
Eventos de sesión y conversación
Estos eventos llegan cuando se establece la conexión y después de cada cambio de configuración:
session.created: la sesión está abierta; el evento contiene la configuración de la sesiónsession.updated: la configuración se ha actualizado correctamenteconversation.created: el canal de conversación está configurado
Eventos del búfer de audio
Estos eventos te informan sobre la actividad de voz que detecta el VAD:
input_audio_buffer.speech_started: el VAD detecta que el usuario ha empezado a hablarinput_audio_buffer.speech_stopped: el VAD detecta el final del hablainput_audio_buffer.committed: el búfer de audio se ha confirmado como un mensaje
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// El usuario está hablando: muestra un indicador visual
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// El usuario ha terminado: oculta el indicador
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// El mensaje de audio se está procesando
showProcessingIndicator(true);
break;
}
});
Eventos de audio de respuesta
El audio de respuesta se transmite mediante dos eventos.
response.output_audio.delta
Cada delta contiene un fragmento de audio codificado en base64. Recógelos y reprodúcelos en orden:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Indica que se ha enviado todo el audio de la respuesta:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Eventos de transcripción
La API puede transcribir tanto el audio del usuario como el audio de la respuesta:
conversation.item.input_audio_transcription.completed: una transcripción de lo que ha dicho el usuarioresponse.output_audio_transcript.delta: una transcripción en flujo continuo de la respuesta del agente
case "conversation.item.input_audio_transcription.completed":
console.log("El usuario ha dicho:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Eventos de texto
Si el agente genera texto (además del audio o en su lugar), recibirás:
response.text.delta: un fragmento de texto en flujo continuo
{
"type": "response.text.delta",
"delta": "Tu pedido ha sido"
}
Eventos de llamada a funciones
Cuando el agente decide llamar a una función, se emiten dos eventos:
response.function_call_arguments.delta: los argumentos de la función, en flujo continuoresponse.function_call_arguments.done: la llamada a la función completa con todos sus argumentos
La lección 13, sobre la llamada a funciones por voz, trata estos eventos en detalle.
response.done
Este evento marca el final completo de una respuesta. Contiene un resumen de la respuesta, incluidas las estadísticas de uso:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
El evento de error
Este evento notifica errores. Según la referencia de xAI, la mayoría de los errores son recuperables y la conexión WebSocket permanece abierta:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Formato de audio no válido especificado"
}
}
Tu aplicación debe registrar estos errores y, dependiendo de su gravedad, mostrar un mensaje al usuario o intentar solucionar el problema automáticamente.
Puntos clave
- El servidor envía eventos para cada paso: detección de voz, audio, transcripción, texto y errores
- El audio de respuesta llega como fragmentos en base64 a través de
response.output_audio.delta - Hay transcripciones disponibles tanto para la entrada del usuario como para la salida del agente
response.donemarca el final de una respuesta completa- La mayoría de los errores notificados mediante el evento
errorson recuperables: la conexión permanece abierta