Събитията session.created и session.updated
На тази страница
Обновено на 3 ноември 2026 г., въз основа на страницата Speech to Speech на xAI и справочника за Voice API. Справочникът не описва подробно съдържанието на обекта
sessionв тези събития; идентификаторът, който трябва да запазите, е този на разговора –conversation.id, от който зависи възобновяването на сесията. Източници: Speech to Speech · Voice API.
Сървърни събития за сесията
Докато работите с Voice Agent API, сървърът Ви информира за състоянието на сесията чрез JSON събития. Първите, които получавате, са session.created при отваряне на връзката и conversation.created. След това следва session.updated след всяка конфигурация, която изпратите.
session.created
Сървърът изпраща това събитие автоматично веднага щом WebSocket връзката се отвори. Според справочника то съдържа конфигурацията на сесията, но полетата ѝ не са детайлизирани. Вместо да правите предположения за стойности по подразбиране, регистрирайте събитието веднъж, за да видите какво връща сървърът, и след това изпратете собствената си конфигурация.
Какво да правите, когато пристигне session.created
Вашето приложение трябва:
- Да регистрира събитието за целите на отстраняването на грешки.
- Незабавно да изпрати Вашето
session.updateс желаната конфигурация. - Да изпразни аудио буфера, който сте запълнили, докато чакахте връзката.
Третата точка произтича от съвета на xAI за намаляване на възприеманото забавяне: започнете да записвате от микрофона веднага щом екранът се отвори, без да чакате връзката, запазете пробите в паметта и ги изпратете веднага щом връзката е готова и конфигурацията е изпратена.
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
Това събитие потвърждава Вашето session.update: сесията е конфигурирана. За някои настройки документацията посочва, че приложената стойност се изпраща обратно тук, както е при таблицата за замяна на произношението (replace). Невалидна конфигурация от друга страна се отхвърля със събитие error, което описва проблема; сесията остава отворена и запазва предишната си конфигурация.
Проверка на конфигурацията
Сравнете върнатите стойности с изпратените от Вас: така ще откриете настройка, която е била игнорирана.
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
Сървърът изпраща и събитие conversation.created, което носи идентификатора на разговора:
{
"type": "conversation.created",
"conversation": {
"id": "conv_xyz789"
}
}
Запазете този идентификатор: той е това, което прави възобновяването на сесията възможно. По подразбиране връзката губи историята на разговора, когато WebSocket се затвори. Ако изпратите "resumption": {"enabled": true} в session.update, сървърът кешира всяка размяна на реплики. Когато се свържете отново, отворете отново WebSocket с ?conversation_id=<id> и активирайте отново възобновяването: предишните размени ще бъдат възпроизведени преди първия Ви нов ход. Историята се изтрива след 30 минути неактивност.
Пълна последователност на стартиране
Обобщено, ето реда на събитията при стартиране на гласова сесия, както е описано в справочника:
- WebSocket връзката се отваря
- Получавате
session.created(сървър → клиент) - Получавате
conversation.created(сървър → клиент) - Изпращате
session.update(клиент → сървър) - Получавате
session.updated(сървър → клиент)
Ключови изводи
session.createdпристига при отваряне на връзката и съдържа конфигурацията на сесията, чиито полета справочникът не детайлизираsession.updatedпотвърждава Вашата конфигурация; невалидна конфигурация връща събитиеerror- Записвайте от микрофона преди връзката и изпразнете буфера веднага щом тя е готова
conversation.createdносиconversation.id, който запазвате за възобновяване на сесията- Възобновяването изисква
resumption.enabledпри всяка връзка, а историята изтича след 30 минути неактивност