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

Palvelimen lähettämät tapahtumat

Oppitunti 10 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Vastaanottamasi viestit
  2. Istunto- ja keskustelutapahtumat
  3. Äänipuskuritapahtumat
  4. Vastausäänitapahtumat
  5. Transkriptiotapahtumat
  6. Tekstitapahtumat
  7. Funktiokutsutapahtumat
  8. response.done
  9. Virhetapahtuma
  10. Keskeiset asiat

Vastaanottamasi viestit

Palvelin lähettää lukuisia tapahtumia pitääkseen sinut ajan tasalla keskustelun tilasta, toimittaakseen vastausäänen ja raportoidakseen virheistä. Näiden tapahtumien ymmärtäminen on välttämätöntä reagoivan ja luotettavan sovelluksen rakentamiseksi.

Istunto- ja keskustelutapahtumat

Nämä tapahtumat saapuvat yhteyden muodostamisen yhteydessä ja jokaisen kokoonpanomuutoksen jälkeen:

  • session.created: istunto on avattu; tapahtuma sisältää istunnon kokoonpanon
  • session.updated: kokoonpano päivitettiin onnistuneesti
  • conversation.created: keskustelukanava on otettu käyttöön

Äänipuskuritapahtumat

Nämä tapahtumat kertovat VAD:n (Voice Activity Detection) havaitsemasta puheaktiivisuudesta:

  • input_audio_buffer.speech_started: VAD havaitsee käyttäjän alkaneen puhua
  • input_audio_buffer.speech_stopped: VAD havaitsee puheen päättymisen
  • input_audio_buffer.committed: äänipuskuri on vahvistettu viestinä
ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "input_audio_buffer.speech_started":
      // Käyttäjä puhuu: näytä visuaalinen ilmaisin
      showSpeakingIndicator(true);
      break;

    case "input_audio_buffer.speech_stopped":
      // Käyttäjä on lopettanut: piilota ilmaisin
      showSpeakingIndicator(false);
      break;

    case "input_audio_buffer.committed":
      // Ääniviestiä käsitellään
      showProcessingIndicator(true);
      break;
  }
});

Vastausäänitapahtumat

Vastausääni virtaa kahden tapahtuman kautta.

response.output_audio.delta

Jokainen delta sisältää base64-koodatun äänipalan. Kerää ne ja toista ne oikeassa järjestyksessä:

{
  "type": "response.output_audio.delta",
  "delta": "SGVsbG8gV29ybGQ...",
  "item_id": "item_resp_001",
  "output_index": 0,
  "content_index": 0
}
case "response.output_audio.delta":
  const audioChunk = base64ToArrayBuffer(event.delta);
  audioPlayer.enqueue(audioChunk);
  break;

response.output_audio.done

Ilmoittaa, että kaikki vastausääni on lähetetty:

{
  "type": "response.output_audio.done",
  "item_id": "item_resp_001"
}

Transkriptiotapahtumat

API voi transkriptoida sekä käyttäjän äänen että vastausäänen:

  • conversation.item.input_audio_transcription.completed: transkriptio siitä, mitä käyttäjä sanoi
  • response.output_audio_transcript.delta: agentin vastauksen suoratoistettu transkriptio
case "conversation.item.input_audio_transcription.completed":
  console.log("Käyttäjä sanoi:", event.transcript);
  displayUserMessage(event.transcript);
  break;

case "response.output_audio_transcript.delta":
  appendAgentTranscript(event.delta);
  break;

Tekstitapahtumat

Jos agentti tuottaa tekstiä (äänen lisäksi tai sen sijaan), vastaanotat:

  • response.text.delta: suoratoistetun tekstikatkelman
{
  "type": "response.text.delta",
  "delta": "Tilauksesi on"
}

Funktiokutsutapahtumat

Kun agentti päättää kutsua funktion, lähetetään kaksi tapahtumaa:

  • response.function_call_arguments.delta: funktion argumentit suoratoistettuna
  • response.function_call_arguments.done: täydellinen funktiokutsu kaikilla argumenteillaan

Oppitunti 13, joka käsittelee äänipohjaista funktiokutsua, kattaa nämä tapahtumat yksityiskohtaisesti.

response.done

Tämä tapahtuma merkitsee vastauksen täydellisen päättymisen. Se sisältää yhteenvedon vastauksesta, mukaan lukien käyttötilastot:

{
  "type": "response.done",
  "response": {
    "id": "resp_001",
    "status": "completed",
    "output": [...]
  }
}

Virhetapahtuma

Tämä tapahtuma raportoi virheet. xAI:n viitetietojen mukaan useimmat virheet ovat korjattavissa, ja WebSocket-yhteys pysyy auki:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Määritetty virheellinen äänimuoto"
  }
}

Sovelluksesi tulisi kirjata nämä virheet ja niiden vakavuudesta riippuen joko näyttää käyttäjälle viesti tai yrittää korjata ongelma automaattisesti.

Keskeiset asiat

  • Palvelin lähettää tapahtumia jokaisesta vaiheesta: äänen havaitseminen, ääni, transkriptio, teksti ja virheet
  • Vastausääni saapuu base64-paloina tapahtuman response.output_audio.delta kautta
  • Transkriptiot ovat saatavilla sekä käyttäjän syötteelle että agentin tulosteelle
  • response.done merkitsee täydellisen vastauksen päättymisen
  • Useimmat tapahtuman error kautta raportoidut virheet ovat korjattavissa: yhteys pysyy auki