Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Gli eventi session.created e session.updated

Lezione 4 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Eventi di sessione del server
  2. session.created
  3. session.updated
  4. conversation.created
  5. La sequenza completa di avvio
  6. Punti chiave

Aggiornato il 3 novembre 2026, sulla base della pagina Speech to Speech di xAI e del riferimento dell’API Voice. Il riferimento non dettaglia il contenuto dell’oggetto session in questi eventi; l’ID da conservare è quello della conversazione, conversation.id, su cui si basa la ripresa della sessione. Fonti: Speech to Speech · Voice API.

Eventi di sessione del server

Mentre lavori con l’API Voice Agent, il server ti tiene informato sullo stato della sessione tramite eventi JSON. I primi che ricevi sono session.created, quando la connessione si apre, e conversation.created. Segue poi session.updated, dopo ogni configurazione che invii.

session.created

Il server invia questo evento automaticamente non appena la connessione WebSocket si apre. Secondo il riferimento, contiene la configurazione della sessione, ma i suoi campi non sono dettagliati. Piuttosto che assumere valori predefiniti, registra l’evento una volta per vedere cosa restituisce il server, quindi invia la tua configurazione.

Cosa fare quando arriva session.created

La tua app dovrebbe:

  1. Registrare l’evento, per il debug
  2. Inviare immediatamente il tuo session.update con la configurazione desiderata
  3. Svuotare il buffer audio che hai riempito mentre attendevi la connessione

Il terzo punto deriva dal consiglio di xAI per ridurre la latenza percepita: inizia a catturare l’audio dal microfono non appena la schermata si apre, senza attendere la connessione, mantieni i campioni in memoria, quindi inviali non appena la connessione è pronta e la configurazione è stata inviata.

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "session.created":
      console.log("Session created:", event.session);
      // Invia la configurazione
      ws.send(JSON.stringify({
        type: "session.update",
        session: {
          instructions: "You are a voice assistant.",
          voice: "rex",
          turn_detection: { type: "server_vad" }
        }
      }));
      // Quindi invia l'audio catturato durante l'attesa della connessione
      flushMicBuffer(ws);
      break;
  }
});

session.updated

Questo evento conferma il tuo session.update: la sessione è configurata. Per alcune impostazioni, la documentazione afferma che il valore applicato viene rispedito qui, come nel caso della tabella di sostituzione della pronuncia (replace). Una configurazione non valida, invece, viene rifiutata con un evento error che descrive il problema; la sessione rimane aperta e mantiene la sua configurazione precedente.

Verifica la configurazione

Confronta i valori restituiti con quelli che hai inviato: è così che individui un’impostazione ignorata.

case "session.updated":
  const s = event.session;
  console.log("Configured voice:", s.voice);
  console.log("Number of tools:", s.tools?.length ?? 0);
  break;

case "error":
  console.error("Configuration rejected:", event);
  break;

conversation.created

Il server invia anche un evento conversation.created, che contiene l’ID della conversazione:

{
  "type": "conversation.created",
  "conversation": {
    "id": "conv_xyz789"
  }
}

Conserva questo ID: è ciò che rende possibile la ripresa della sessione. Per impostazione predefinita, una connessione perde la cronologia della conversazione quando il WebSocket si chiude. Se invii "resumption": {"enabled": true} in session.update, il server memorizza nella cache ogni turno. Quando ti riconnetti, riapri il WebSocket con ?conversation_id=<id> e abilita nuovamente la ripresa: i turni precedenti vengono riprodotti prima del tuo primo nuovo turno. La cronologia viene eliminata dopo 30 minuti di inattività.

La sequenza completa di avvio

Per riassumere, ecco l’ordine degli eventi all’avvio di una sessione vocale, così come descritto nel riferimento:

  1. Il WebSocket si apre
  2. Ricevi session.created (server → client)
  3. Ricevi conversation.created (server → client)
  4. Invii session.update (client → server)
  5. Ricevi session.updated (server → client)

Punti chiave

  • session.created arriva all’apertura della connessione e contiene la configurazione della sessione, i cui campi non sono dettagliati nel riferimento
  • session.updated conferma la tua configurazione; una configurazione non valida restituisce un evento error
  • Cattura l’audio dal microfono prima della connessione e svuota il buffer non appena è pronto
  • conversation.created contiene il conversation.id, che devi conservare per la ripresa della sessione
  • La ripresa richiede resumption.enabled su ogni connessione e la cronologia scade dopo 30 minuti di inattività