Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Behärska WebSocket-händelser

Lektion 4 av 14 Uppdaterad 29 juli 2026 Medelnivå
På denna sida
  1. Ett samtal byggt av JSON-händelser
  2. Vad din app skickar
  3. Vad servern skickar tillbaka
  4. Skelettet för en klient
  5. Den knepiga delen: avbrott
  6. Viktiga punkter

Ett samtal byggt av JSON-händelser

Under huven är ett röstsamtal med Voice Agent bara en ström av JSON-meddelanden som flödar båda vägarna över WebSocket-anslutningen. Varje meddelande har ett fält type som anger vad det är. Innan du kan denna terminologi fungerar din klient på tur och chans. När du väl behärskar den vet du exakt var du ska kliva in för att bryta ett svar, visa en transkription eller återhämta dig från ett fel.

Händelserna delas in i två familjer, beroende på vilken väg de färdas. De du skickar styr sessionen; de du tar emot berättar vad som händer på servern.

Vad din app skickar

Dina utgående meddelanden täcker fyra behov: konfigurera sessionen, mata ljudbufferten, hantera samtalshistoriken och styra svarsgenereringen.

HändelseSyfte
session.updateKonfigurerar eller omkonfigurerar sessionen (röst, instruktioner, verktyg, VAD, ljudformat)
input_audio_buffer.appendSkickar en base64-kodad ljudbit, kontinuerligt medan användaren talar
input_audio_buffer.commitBekräftar buffertens aktuella innehåll som användarens meddelande; behövs endast i manuellt läge
input_audio_buffer.clearTömmer ljudbufferten utan att bearbeta den
conversation.item.createLägger till ett objekt i samtalet: ett textmeddelande, tidigare historik eller resultatet av ett funktionsanrop
conversation.item.deleteTar bort ett samtalsobjekt via dess ID
response.createBer modellen att generera ett svar; automatiskt i VAD-läge, explicit i manuellt läge
response.cancelAvbryter ett svar som håller på att genereras

Två av dessa meddelanden förtjänar en närmare titt. conversation.item.create är hur du injicerar kontext: det är vad du använder för att återställa historiken från ett tidigare samtal vid starten av en ny session. När det gäller input_audio_buffer.clear kommer den till nytta när användaren uppenbarligen inte sa något värt att bearbeta (ett harklande fångat av en överkänslig mikrofon) och du hellre vill börja om från en ren buffert än låta modellen tolka brus.

Vad servern skickar tillbaka

Den inkommande strömmen är livligare, eftersom den ger en löpande kommentar till varje bearbetningssteg.

HändelseBetydelse
session.createdSessionen är öppen
session.updatedEn konfigurationsuppdatering har tillämpats
conversation.createdSamtalet är inställt
input_audio_buffer.speech_startedVAD upptäcker att användaren har börjat tala
input_audio_buffer.speech_stoppedVAD upptäcker att användaren har slutat tala
input_audio_buffer.committedLjudbufferten har bekräftats, av VAD eller manuellt
response.createdEtt svar håller på att genereras
response.output_audio.deltaEn bit av svars-ljudet, i base64
response.output_audio.doneSvars-ljudet är komplett
response.output_audio_transcript.deltaTexttranskriptionen av ljudet, strömmad
response.doneSvaret är helt avslutat
conversation.item.input_audio_transcription.completedTranskriptionen av användarens meddelande är tillgänglig
response.text.deltaStrömmad text, för icke-röstsvar
response.function_call_arguments.deltaArgumenten för ett funktionsanrop, strömmade
response.function_call_arguments.doneFunktionsanropet är klart och redo att köras
errorEtt fel har inträffat; de flesta fel går att återhämta sig från

Den sista kräver en varning. Att ta emot error betyder inte att sessionen är förlorad. Enligt xAI:s referens är de flesta fel återställbara och sessionen förblir öppen, så en klient som stänger anslutningen vid första error bryter ett samtal som kunde ha fortsatt. Logga det, informera användaren vid behov, men håll socketen öppen.

Skelettet för en klient

I praktiken handlar allt om en switch på msg.type. Här är den minimala formen för en JavaScript-klient:

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

  switch (msg.type) {
    case "session.created":
      // Skicka session.update med konfigurationen
      break;

    case "input_audio_buffer.speech_started":
      // Användaren talar: stoppa svars-ljudet som spelas
      break;

    case "response.output_audio.delta":
      // Avkoda base64 och spela ljudet
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Kör funktionen och skicka tillbaka resultatet
      handleFunctionCall(msg);
      break;

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

Fyra grenar räcker för att köra en agent: konfigurera när sessionen öppnas, reagera när användaren börjar tala, spela inkommande ljud och kör funktioner. De andra händelserna berikar gränssnittet och kan vänta till en andra iteration.

Den knepiga delen: avbrott

Barge-in, när användaren börjar tala medan agenten fortfarande svarar, är där en slarvig implementation avslöjas. Servern avbryter det aktuella svaret på egen hand och börjar generera ett nytt från det den just hört. Men medan servern har slutat skicka, har din app fortfarande flera sekunder av redan mottaget ljud i sin utmatningsbuffert.

Om du inte gör något fortsätter användaren att höra meningen de just avbröt medan de pratar över den, och agenten framstår som om den inte lyssnar. Så snart du tar emot speech_started måste du alltså stoppa ljudet som spelas, tömma utmatningsbufferten så att du inte spelar gammalt ljud, och låta servern bearbeta den nya inmatningen. Dessa två steg tar några rader kod och gör hela skillnaden mellan en agent du kan avbryta och en som pratar ut i tomma intet.

Viktiga punkter

  • Klienthändelser täcker konfiguration, sändning av ljud, hantering av samtal och styrning av svar
  • Serverhändelser rapporterar tal-detektering, ljudbitar, transkriptioner och funktionsanrop
  • VAD hanterar avbrott (barge-in) automatiskt
  • De flesta error-händelser är återställbara: stäng inte anslutningen, hantera felet
  • I manuellt läge måste du explicit anropa commit och sedan response.create