Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Savladaj WebSocket događaje

Lekcija 4 od 14 Ažurirano 29. srpnja 2026. Srednja razina
Na ovoj stranici
  1. Razgovor sastavljen od JSON događaja
  2. Što tvoja aplikacija šalje
  3. Što poslužitelj šalje natrag
  4. Kostur klijenta
  5. Zamršeni dio: prekidi
  6. Ključne točke

Razgovor sastavljen od JSON događaja

Ispod haube, glasovna razmjena s Voice Agentom nije ništa drugo do tok JSON poruka koji teče u oba smjera preko WebSocket veze. Svaka poruka ima polje type koje govori o čemu se radi. Dok ne naučiš taj rječnik, tvoj klijent radi na sreću. Čim ga savladaš, točno znaš gdje intervenirati da prekineš odgovor, prikažeš transkript ili se oporaviš od pogreške.

Događaji se dijele u dvije obitelji, ovisno o smjeru putovanja. Oni koje šalješ pokreću sesiju; oni koje primaš govore ti što se događa na poslužitelju.

Što tvoja aplikacija šalje

Tvoje odlazne poruke pokrivaju četiri potrebe: konfiguriranje sesije, punjenje audio međuspremnika, upravljanje poviješću razgovora i kontrolu generiranja odgovora.

DogađajSvrha
session.updateKonfigurira ili rekonfigurira sesiju (glas, upute, alati, VAD, audio format)
input_audio_buffer.appendŠalje dio audio zapisa kodiran u base64, kontinuirano dok korisnik govori
input_audio_buffer.commitPotvrđuje sadržaj trenutnog međuspremnika kao korisnikovu poruku; potrebno samo u ručnom načinu rada
input_audio_buffer.clearPrazni audio međuspremnik bez obrade
conversation.item.createDodaje stavku u razgovor: tekstualnu poruku, raniju povijest ili rezultat poziva funkcije
conversation.item.deleteBriše stavku razgovora prema njezinom ID-u
response.createTraži od modela da generira odgovor; automatski u VAD načinu, eksplicitno u ručnom načinu
response.cancelPoništava odgovor koji se generira

Dvije od ovih poruka zaslužuju bliži pogled. conversation.item.create je način na koji ubacuješ kontekst: to koristiš za vraćanje povijesti ranijeg poziva na početku nove sesije. Što se tiče input_audio_buffer.clear, on je koristan kada korisnik očito nije rekao ništa vrijedno obrade (na primjer, kašalj uhvaćen preosjetljivim mikrofonom) i radije želiš krenuti ispočetka s praznim međuspremnikom nego dopustiti modelu da tumači šum.

Što poslužitelj šalje natrag

Dolazni tok je življi jer daje komentar u stvarnom vremenu za svaki korak obrade.

DogađajZnačenje
session.createdSesija je otvorena
session.updatedAžuriranje konfiguracije je primijenjeno
conversation.createdRazgovor je postavljen
input_audio_buffer.speech_startedVAD detektira da je korisnik počeo govoriti
input_audio_buffer.speech_stoppedVAD detektira da je korisnik prestao govoriti
input_audio_buffer.committedAudio međuspremnik je potvrđen, putem VAD-a ili ručno
response.createdGenerira se odgovor
response.output_audio.deltaDio odgovarajućeg audio zapisa, u base64 formatu
response.output_audio.doneAudio odgovor je potpun
response.output_audio_transcript.deltaTekstualni transkript audio zapisa, strujno
response.doneOdgovor je u potpunosti završen
conversation.item.input_audio_transcription.completedTranskript korisnikove poruke je dostupan
response.text.deltaStrujni tekst, za odgovore koji nisu glasovni
response.function_call_arguments.deltaArgumenti poziva funkcije, strujno
response.function_call_arguments.donePoziv funkcije je potpun i spreman za izvršavanje
errorDošlo je do pogreške; većina pogrešaka je moguće oporaviti

Posljednja stavka zahtijeva upozorenje. Primitak error ne znači da je sesija izgubljena. Prema xAI referenci, većina pogrešaka je moguće oporaviti i sesija ostaje otvorena, stoga klijent koji zatvori vezu pri prvoj error poruci prekida razgovor koji je mogao nastaviti. Zabilježi pogrešku, obavijesti korisnika ako je potrebno, ali drži socket otvorenim.

Kostur klijenta

U praksi, sve se svodi na switch naredbu temeljenu na msg.type. Evo minimalnog oblika JavaScript klijenta:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Pošalji session.update s konfiguracijom
      break;

    case "input_audio_buffer.speech_started":
      // Korisnik govori: zaustavi reprodukciju audio odgovora
      break;

    case "response.output_audio.delta":
      // Dekodiraj base64 i reproduciraj audio
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Pokreni funkciju i pošalji natrag rezultat
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Voice Agent error:", msg.error);
      break;
  }
};

Četiri grane dovoljne su za pokretanje agenta: konfiguriraj pri otvaranju sesije, reagiraj kada korisnik počne govoriti, reproduciraj dolazni audio i pokreni funkcije. Ostali događaji obogaćuju sučelje i mogu pričekati drugu iteraciju.

Zamršeni dio: prekidi

Barge-in, situacija kada korisnik počne govoriti dok agent još odgovara, je trenutak u kojem se vidi loša implementacija. Poslužitelj samostalno poništava trenutni odgovor i počinje generirati novi na temelju onoga što je upravo čuo. No, dok je poslužitelj prestao slati, tvoja aplikacija i dalje drži nekoliko sekundi već primljenog audio zapisa u svom izlaznom međuspremniku.

Ako ne učiniš ništa, korisnik će i dalje čuti rečenicu koju je upravo prekinuo dok govori preko nje, a agent će djelovati kao da ne sluša. Stoga, čim primiš speech_started, zaustavi audio koji se reproducira, isprazni izlazni međuspremnik kako ne bi reproducirao zastarjeli zvuk i pusti poslužitelju da obradi novi unos. Ta dva koraka zahtijevaju nekoliko redaka koda, a čine svu razliku između agenta kojeg možeš prekinuti i onoga koji govori u prazninu.

Ključne točke

  • Događaji klijenta pokrivaju konfiguraciju, slanje audija, upravljanje razgovorom i kontrolu odgovora
  • Događaji poslužitelja izvještavaju o detekciji govora, audio dijelovima, transkriptima i pozivima funkcija
  • VAD automatski rukuje prekidima (barge-in)
  • Većina događaja error je moguće oporaviti: ne zatvaraj vezu, obradi pogrešku
  • U ručnom načinu rada, moraš eksplicitno pozvati commit, a zatim response.create