Gli eventi session.created e session.updated
In questa pagina
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
sessionin 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:
- Registrare l’evento, per il debug
- Inviare immediatamente il tuo
session.updatecon la configurazione desiderata - 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:
- Il WebSocket si apre
- Ricevi
session.created(server → client) - Ricevi
conversation.created(server → client) - Invii
session.update(client → server) - Ricevi
session.updated(server → client)
Punti chiave
session.createdarriva all’apertura della connessione e contiene la configurazione della sessione, i cui campi non sono dettagliati nel riferimentosession.updatedconferma la tua configurazione; una configurazione non valida restituisce un eventoerror- Cattura l’audio dal microfono prima della connessione e svuota il buffer non appena è pronto
conversation.createdcontiene ilconversation.id, che devi conservare per la ripresa della sessione- La ripresa richiede
resumption.enabledsu ogni connessione e la cronologia scade dopo 30 minuti di inattività