Evenimentele session.created și session.updated
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginii Speech to Speech xAI și a referinței Voice API. Referința nu detaliază conținutul obiectului
sessiondin aceste evenimente; identificatorul de reținut este cel al conversației,conversation.id, de care depinde reluarea sesiunii. Surse: Speech to Speech · Voice API.
Evenimente de sesiune pe server
În timp ce lucrați cu Voice Agent API, serverul vă informează despre starea sesiunii prin evenimente JSON. Primele evenimente pe care le primiți sunt session.created, la deschiderea conexiunii, și conversation.created. Urmează apoi session.updated, după fiecare configurare pe care o trimiteți.
session.created
Serverul trimite acest eveniment automat imediat ce conexiunea WebSocket se deschide. Conform referinței, acesta conține configurația sesiunii, dar câmpurile sale nu sunt detaliate. În loc să presupuneți valori implicite, înregistrați-l o dată în jurnal pentru a vedea ce returnează serverul, apoi trimiteți propria configurație.
Ce trebuie făcut la primirea lui session.created
Aplicația dumneavoastră ar trebui să:
- Înregistreze evenimentul în jurnal, pentru depanare
- Trimită imediat comanda
session.updatecu configurația dorită - Golească buffer-ul audio pe care l-ați umplut în așteptarea conexiunii
Al treilea punct provine din sfatul xAI pentru reducerea latenței percepute: începeți captarea microfonului imediat ce se deschide ecranul, fără a aștepta conexiunea, păstrați eșantioanele în memorie, apoi trimiteți-le imediat ce conexiunea este gata și configurația a fost trimisă.
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "session.created":
console.log("Session created:", event.session);
// Send the configuration
ws.send(JSON.stringify({
type: "session.update",
session: {
instructions: "You are a voice assistant.",
voice: "rex",
turn_detection: { type: "server_vad" }
}
}));
// Then send the audio captured while waiting for the connection
flushMicBuffer(ws);
break;
}
});
session.updated
Acest eveniment confirmă comanda session.update: sesiunea este configurată. Pentru anumite setări, documentația precizează că valoarea aplicată este returnată aici, ca în cazul tabelului de înlocuire a pronunției (replace). În schimb, o configurație invalidă este respinsă printr-un eveniment error care descrie problema; sesiunea rămâne deschisă și își păstrează configurația anterioară.
Verificarea configurației
Comparați valorile returnate cu cele pe care le-ați trimis: așa depistați o setare care a fost ignorată.
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
Serverul trimite, de asemenea, un eveniment conversation.created, care conține identificatorul conversației:
{
"type": "conversation.created",
"conversation": {
"id": "conv_xyz789"
}
}
Păstrați acest identificator: acesta este cel care face posibilă reluarea sesiunii. În mod implicit, o conexiune pierde istoricul conversației când WebSocket-ul se închide. Dacă trimiteți "resumption": {"enabled": true} în session.update, serverul cachează fiecare tur de dialog. Când vă reconectați, redeschideți WebSocket-ul cu ?conversation_id=<id> și activați din nou reluarea: tururile anterioare sunt redate înainte de primul dumneavoastră tur nou. Istoricul este șters după 30 de minute de inactivitate.
Secvența completă de pornire
Pentru a rezuma, iată ordinea evenimentelor la startul unei sesiuni vocale, așa cum o descrie referința:
- WebSocket-ul se deschide
- Primiți
session.created(server → client) - Primiți
conversation.created(server → client) - Trimiteți
session.update(client → server) - Primiți
session.updated(server → client)
Puncte cheie
session.createdsosește la deschiderea conexiunii și conține configurația sesiunii, ale cărei câmpuri nu sunt detaliate în referințăsession.updatedconfirmă configurația dumneavoastră; o configurație invalidă returnează un evenimenterror- Captati microfonul înainte de conexiune și goliți buffer-ul imediat ce este gata
conversation.createdconțineconversation.id, pe care îl păstrați pentru reluarea sesiunii- Reluarea necesită
resumption.enabledla fiecare conexiune, iar istoricul expiră după 30 de minute de inactivitate