Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

WebSocket-events beheersen

Les 4 van 14 Bijgewerkt op 29 juli 2026 Gemiddeld
Op deze pagina
  1. Een gesprek opgebouwd uit JSON-events
  2. Wat uw app verstuurt
  3. Wat de server terugstuurt
  4. Het skelet van een client
  5. Het lastige deel: onderbrekingen
  6. Belangrijkste punten

Een gesprek opgebouwd uit JSON-events

Onder de motorkap is een spraakuitwisseling met de Voice Agent niets meer dan een stroom JSON-berichten die in beide richtingen vloeien via de WebSocket-verbinding. Elk bericht bevat een type-veld dat aangeeft wat het is. Zolang u deze vocabulaire niet kent, werkt uw client op goed geluk. Zodra u ze wel kent, weet u precies waar u moet ingrijpen om een antwoord af te breken, een transcript weer te geven of te herstellen na een fout.

Events vallen in twee families, afhankelijk van de reisrichting. Diegene die u verstuurt, sturen de sessie aan; diegene die u ontvangt, vertellen u wat er op de server gebeurt.

Wat uw app verstuurt

Uw uitgaande berichten dekken vier behoeften: de sessie configureren, de audiobuffer voeden, de gespreksgeschiedenis beheren en het genereren van antwoorden sturen.

EventDoel
session.updateConfigureert of herconfigureert de sessie (spraak, instructies, tools, VAD, audioformaat)
input_audio_buffer.appendVerstuurt een base64-gecodeerd audiofragment, continu terwijl de gebruiker spreekt
input_audio_buffer.commitBevestigt de huidige bufferinhoud als bericht van de gebruiker; alleen nodig in handmatige modus
input_audio_buffer.clearMaakt de audiobuffer leeg zonder deze te verwerken
conversation.item.createVoegt een item toe aan het gesprek: een tekstbericht, eerdere geschiedenis of het resultaat van een functieaanroep
conversation.item.deleteVerwijdert een gespreksitem op basis van de ID
response.createVraagt het model een antwoord te genereren; automatisch in VAD-modus, expliciet in handmatige modus
response.cancelBreekt een antwoord af dat wordt gegenereerd

Twee van deze berichten verdienen nadere aandacht. conversation.item.create is de manier om context injecteren: dit gebruikt u om de geschiedenis van een eerder gesprek te herstellen aan het begin van een nieuwe sessie. Wat input_audio_buffer.clear betreft, komt dit van pas wanneer de gebruiker duidelijk niets gezegd heeft dat verwerking waard is (een keelschraap opgepikt door een te gevoelige microfoon) en u liever opnieuw begint met een schone buffer dan het model ruis laat interpreteren.

Wat de server terugstuurt

De inkomende stroom is drukker, omdat deze een lopend commentaar geeft op elke verwerkingsstap.

EventBetekenis
session.createdDe sessie is geopend
session.updatedEen configuratie-update is toegepast
conversation.createdHet gesprek is ingesteld
input_audio_buffer.speech_startedVAD detecteert dat de gebruiker is begonnen met spreken
input_audio_buffer.speech_stoppedVAD detecteert dat de gebruiker is gestopt met spreken
input_audio_buffer.committedDe audiobuffer is bevestigd, door VAD of handmatig
response.createdEen antwoord wordt gegenereerd
response.output_audio.deltaEen fragment van het antwoordaudio, in base64
response.output_audio.doneDe antwoordaudio is voltooid
response.output_audio_transcript.deltaHet teksttranscript van de audio, gestreamd
response.doneHet antwoord is volledig voltooid
conversation.item.input_audio_transcription.completedHet transcript van het bericht van de gebruiker is beschikbaar
response.text.deltaGestreamde tekst, voor niet-spraakantwoorden
response.function_call_arguments.deltaDe argumenten van een functieaanroep, gestreamd
response.function_call_arguments.doneDe functieaanroep is voltooid en klaar om uit te voeren
errorEr is een fout opgetreden; de meeste fouten zijn herstelbaar

Dat laatste verdient een waarschuwing. Het ontvangen van error betekent niet dat de sessie verloren is. Volgens de xAI-referentie zijn de meeste fouten herstelbaar en blijft de sessie open, dus een client die de verbinding sluit bij de eerste error verbreekt een gesprek dat had kunnen doorgaan. Log het, informeer de gebruiker indien nodig, maar houd de socket open.

Het skelet van een client

In de praktijk komt alles neer op een switch op msg.type. Hier is de minimale vorm van een JavaScript-client:

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

  switch (msg.type) {
    case "session.created":
      // Stuur session.update met de configuratie
      break;

    case "input_audio_buffer.speech_started":
      // De gebruiker spreekt: stop de afspelende antwoordaudio
      break;

    case "response.output_audio.delta":
      // Decodeer de base64 en speel de audio af
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Voer de functie uit en stuur het resultaat terug
      handleFunctionCall(msg);
      break;

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

Vier takken volstaan om een agent te laten draaien: configureer bij het openen van de sessie, reageer wanneer de gebruiker begint te spreken, speel inkomende audio af en voer functies uit. De andere events verrijken de interface en kunnen wachten op een tweede iteratie.

Het lastige deel: onderbrekingen

Barge-in, wanneer de gebruiker begint te praten terwijl de agent nog antwoordt, is waar een slordige implementatie door de mand valt. De server annuleert het huidige antwoord zelfstandig en begint een nieuw te genereren op basis van wat het zojuist heeft gehoord. Maar terwijl de server is gestopt met verzenden, houdt uw app nog steeds enkele seconden aan reeds ontvangen audio vast in de uitvoerbuffer.

Als u niets doet, blijft de gebruiker de zin horen die ze zojuist hebben onderbroken terwijl ze erdoorheen praten, en komt de agent over alsof hij niet luistert. Stop dus zodra u speech_started ontvangt de afspelende audio, leeg de uitvoerbuffer zodat u geen verouderd geluid afspeelt, en laat de server de nieuwe input verwerken. Die twee stappen kosten enkele regels code en maken het verschil tussen een agent die u kunt onderbreken en een die in het luchtledige praat.

Belangrijkste punten

  • Client-events dekken configuratie, het verzenden van audio, het beheren van het gesprek en het sturen van antwoorden
  • Server-events rapporteren spraakdetectie, audiofragmenten, transcripten en functieaanroepen
  • VAD behandelt onderbrekingen (barge-in) automatisch
  • De meeste error-events zijn herstelbaar: sluit de verbinding niet, maar handel de fout af
  • In handmatige modus moet u commit en vervolgens response.create expliciet aanroepen