Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

session.created- ja session.updated-tapahtumat

Oppitunti 4 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Palvelimen istuntotapahtumat
  2. session.created
  3. session.updated
  4. conversation.created
  5. Koko käynnistyssekvenssi
  6. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech -sivun ja Voice API -viitteen perusteella. Viite ei erittele näiden tapahtumien session-objektin sisältöä; säilytettävä tunniste on keskustelun tunniste conversation.id, johon istunnon jatkaminen nojaa. Lähteet: Speech to Speech · Voice API.

Palvelimen istuntotapahtumat

Kun työskentelet Voice Agent API:n kanssa, palvelin pitää sinut ajan tasalla istunnon tilasta JSON-tapahtumien avulla. Ensimmäiset vastaanottamasi tapahtumat ovat session.created, kun yhteys avautuu, ja conversation.created. Tämän jälkeen seuraa session.updated jokaisen lähettämäsi määrityksen jälkeen.

session.created

Palvelin lähettää tämän tapahtuman automaattisesti heti, kun WebSocket-yhteys avautuu. Viitteen mukaan se sisältää istunnon määritykset, mutta sen kenttiä ei ole eritelty. Oletusten tekemisen sijaan kirjaista tapahtuma kerran nähdäksesi, mitä palvelin palauttaa, ja lähetä sen jälkeen oma määrityksesi.

Mitä tehdä, kun session.created saapuu

Sovelluksesi tulisi:

  1. Kirjata tapahtuma virheenkorjausta varten
  2. Lähettää välittömästi haluamasi määrityksen sisältävä session.update
  3. Tyhjentää äänipuskuri, jonka täytit odottaessasi yhteyden muodostumista

Kolmas kohta perustuu xAI:n neuvoon latenssin vähentämiseksi: aloita mikrofonin kaappaus heti näkymän avautuessa odottamatta yhteyttä, pidä näytteet muistissa ja lähetä ne heti, kun yhteys on valmis ja määritys on lähetetty.

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

  switch (event.type) {
    case "session.created":
      console.log("Session created:", event.session);
      // Lähetä määritys
      ws.send(JSON.stringify({
        type: "session.update",
        session: {
          instructions: "You are a voice assistant.",
          voice: "rex",
          turn_detection: { type: "server_vad" }
        }
      }));
      // Lähetä sitten odotusaikana kaapattu ääni
      flushMicBuffer(ws);
      break;
  }
});

session.updated

Tämä tapahtuma kuittaa session.update-komentosi: istunto on määritetty. Joidenkin asetusten osalta dokumentaatio toteaa, että käytetty arvo lähetetään takaisin tässä, kuten ääntämyksen korvaustaulukon (replace) kohdalla. Virheellinen määritys sen sijaan hylätään error-tapahtumalla, joka kuvailee ongelman; istunto pysyy auki ja säilyttää edellisen määrityksensä.

Tarkista määritys

Vertaa palautettuja arvoja lähettämiisi: näin havaitset asetuksen, joka on jätetty huomiotta.

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

Palvelin lähettää myös conversation.created-tapahtuman, joka sisältää keskustelutunnisteen:

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

Säilytä tämä tunniste: se mahdollistaa istunnon jatkamisen. Oletusarvoisesti yhteys menettää keskusteluhistorian WebSocket-yhteyden sulkeutuessa. Jos lähetät "resumption": {"enabled": true} kohdassa session.update, palvelin välimuistaa jokaisen vuoron. Kun muodostat yhteyden uudelleen, avaa WebSocket uudelleen parametrilla ?conversation_id=<id> ja ota jatkaminen uudelleen käyttöön: edelliset vuorot toistetaan ennen ensimmäistä uutta vuoroasi. Historia poistetaan 30 minuutin toimettomuuden jälkeen.

Koko käynnistyssekvenssi

Yhteenvetona tässä on viitteen kuvaama ääni-istunnon käynnistyksen tapahtumajärjestys:

  1. WebSocket avautuu
  2. Vastaanotat session.created (palvelin → asiakas)
  3. Vastaanotat conversation.created (palvelin → asiakas)
  4. Lähetät session.update (asiakas → palvelin)
  5. Vastaanotat session.updated (palvelin → asiakas)

Keskeiset asiat

  • session.created saapuu yhteyden avautuessa ja sisältää istunnon määritykset, joiden kenttiä viite ei erittele
  • session.updated kuittaa määrityksesi; virheellinen määritys palauttaa error-tapahtuman
  • Kaappaa mikrofoni ennen yhteyttä ja tyhjennä puskuri heti, kun se on valmis
  • conversation.created sisältää conversation.id:n, jonka säilytät istunnon jatkamista varten
  • Jatkaminen vaatii resumption.enabled-asetuksen jokaiselle yhteydelle, ja historia vanhenee 30 minuutin toimettomuuden jälkeen