Премини към основното съдържание
Български— Изберете език
Меню

Събитията session.created и session.updated

Урок 4 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Сървърни събития за сесията
  2. session.created
  3. session.updated
  4. conversation.created
  5. Пълна последователност на стартиране
  6. Ключови изводи

Обновено на 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

Вашето приложение трябва:

  1. Да регистрира събитието за целите на отстраняването на грешки.
  2. Незабавно да изпрати Вашето session.update с желаната конфигурация.
  3. Да изпразни аудио буфера, който сте запълнили, докато чакахте връзката.

Третата точка произтича от съвета на 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 минути неактивност.

Пълна последователност на стартиране

Обобщено, ето реда на събитията при стартиране на гласова сесия, както е описано в справочника:

  1. WebSocket връзката се отваря
  2. Получавате session.created (сървър → клиент)
  3. Получавате conversation.created (сървър → клиент)
  4. Изпращате session.update (клиент → сървър)
  5. Получавате session.updated (сървър → клиент)

Ключови изводи

  • session.created пристига при отваряне на връзката и съдържа конфигурацията на сесията, чиито полета справочникът не детайлизира
  • session.updated потвърждава Вашата конфигурация; невалидна конфигурация връща събитие error
  • Записвайте от микрофона преди връзката и изпразнете буфера веднага щом тя е готова
  • conversation.created носи conversation.id, който запазвате за възобновяване на сесията
  • Възобновяването изисква resumption.enabled при всяка връзка, а историята изтича след 30 минути неактивност