Los eventos session.created y session.updated
En esta página
Actualizado el 3 de noviembre de 2026, basándose en la página Speech to Speech de xAI y la referencia de la Voice API. La referencia no detalla el contenido del objeto
sessionen estos eventos; el identificador que debes conservar es el de la conversación,conversation.id, del cual depende la reanudación de sesión. Fuentes: Speech to Speech · Voice API.
Eventos de sesión del servidor
Mientras trabajas con la Voice Agent API, el servidor te mantiene informado sobre el estado de la sesión mediante eventos JSON. Los primeros que recibes son session.created, cuando se abre la conexión, y conversation.created. A continuación llega session.updated, tras cada configuración que envíes.
session.created
El servidor envía este evento automáticamente tan pronto como se abre la conexión WebSocket. Según la referencia, contiene la configuración de la sesión, pero sus campos no están detallados. En lugar de asumir valores por defecto, registra el evento una vez para ver qué devuelve el servidor y, a continuación, envía tu propia configuración.
Qué hacer cuando llega session.created
Tu aplicación debe:
- Registrar el evento, para depuración.
- Enviar inmediatamente tu
session.updatecon la configuración deseada. - Vaciar el búfer de audio que hayas llenado mientras esperabas la conexión.
El tercer punto proviene del consejo de xAI para reducir la latencia percibida: comienza a capturar el micrófono tan pronto como se abra la pantalla, sin esperar a la conexión, mantén las muestras en memoria y envíalas en cuanto la conexión esté lista y se haya enviado la configuración.
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "session.created":
console.log("Sesión creada:", event.session);
// Enviar la configuración
ws.send(JSON.stringify({
type: "session.update",
session: {
instructions: "Eres un asistente de voz.",
voice: "rex",
turn_detection: { type: "server_vad" }
}
}));
// A continuación, enviar el audio capturado mientras se esperaba la conexión
flushMicBuffer(ws);
break;
}
});
session.updated
Este evento confirma tu session.update: la sesión está configurada. Para algunos ajustes, la documentación indica que el valor aplicado se devuelve aquí, como ocurre con la tabla de sustitución de pronunciación (replace). Por el contrario, una configuración no válida se rechaza con un evento error que describe el problema; la sesión permanece abierta y conserva su configuración anterior.
Comprobar la configuración
Compara los valores devueltos con los que enviaste: así es como detectas un ajuste que haya sido ignorado.
case "session.updated":
const s = event.session;
console.log("Voz configurada:", s.voice);
console.log("Número de herramientas:", s.tools?.length ?? 0);
break;
case "error":
console.error("Configuración rechazada:", event);
break;
conversation.created
El servidor también envía un evento conversation.created, que contiene el ID de la conversación:
{
"type": "conversation.created",
"conversation": {
"id": "conv_xyz789"
}
}
Conserva este ID: es lo que hace posible la reanudación de sesión. Por defecto, una conexión pierde el historial de la conversación cuando se cierra el WebSocket. Si envías "resumption": {"enabled": true} en session.update, el servidor almacena en caché cada turno. Cuando te reconectes, vuelve a abrir el WebSocket con ?conversation_id=<id> y habilita de nuevo la reanudación: los turnos anteriores se reproducirán antes de tu primer turno nuevo. El historial se descarta tras 30 minutos de inactividad.
La secuencia completa de inicio
En resumen, este es el orden de los eventos cuando se inicia una sesión de voz, tal como lo describe la referencia:
- Se abre el WebSocket
- Recibes
session.created(servidor → cliente) - Recibes
conversation.created(servidor → cliente) - Envías
session.update(cliente → servidor) - Recibes
session.updated(servidor → cliente)
Puntos clave
session.createdllega cuando se abre la conexión y contiene la configuración de la sesión, cuyos campos la referencia no detallasession.updatedconfirma tu configuración; una configuración no válida devuelve un eventoerror- Captura el micrófono antes de la conexión y vacía el búfer tan pronto como esté lista
conversation.createdcontiene elconversation.id, que debes conservar para la reanudación de sesión- La reanudación requiere
resumption.enableden cada conexión, y el historial caduca tras 30 minutos de inactividad