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

Los eventos session.created y session.updated

Lección 4 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Eventos de sesión del servidor
  2. session.created
  3. session.updated
  4. conversation.created
  5. La secuencia completa de inicio
  6. Puntos clave

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 session en 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:

  1. Registrar el evento, para depuración.
  2. Enviar inmediatamente tu session.update con la configuración deseada.
  3. 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:

  1. Se abre el WebSocket
  2. Recibes session.created (servidor → cliente)
  3. Recibes conversation.created (servidor → cliente)
  4. Envías session.update (cliente → servidor)
  5. Recibes session.updated (servidor → cliente)

Puntos clave

  • session.created llega cuando se abre la conexión y contiene la configuración de la sesión, cuyos campos la referencia no detalla
  • session.updated confirma tu configuración; una configuración no válida devuelve un evento error
  • Captura el micrófono antes de la conexión y vacía el búfer tan pronto como esté lista
  • conversation.created contiene el conversation.id, que debes conservar para la reanudación de sesión
  • La reanudación requiere resumption.enabled en cada conexión, y el historial caduca tras 30 minutos de inactividad