De sessie configureren met session.update
Op deze pagina
Bijgewerkt op 3 november 2026, gebaseerd op de xAI-pagina’s Speech to Speech en Text to Speech: 28 ingebouwde stemmen, en
turn_detectioningesteld alleen via hettype(met optioneleidle_timeout_ms). Bronnen: Speech to Speech · Text to Speech.
Uw voice-agent configureren
Zodra de WebSocket-verbinding tot stand is gebracht en u het session.created-event heeft ontvangen, configureert u de sessie door een session.update-bericht te verzenden. Hier definieert u het gedrag van uw voice-agent: de persoonlijkheid, de stem, de beschikbare tools en de methode voor beurtwisseling (turn detection).
De volledige structuur van session.update
Hieronder ziet u een gedetailleerd configuratievoorbeeld:
{
"type": "session.update",
"session": {
"instructions": "You are a professional voice assistant for a law firm. Answer concisely and precisely. Use a formal tone.",
"voice": "Rex",
"tools": [
{"type": "web_search"},
{
"type": "function",
"name": "look_up_case",
"description": "Looks up a client case by number",
"parameters": {
"type": "object",
"properties": {
"case_number": {
"type": "string",
"description": "Client case number"
}
},
"required": ["case_number"]
}
}
],
"turn_detection": {
"type": "server_vad"
},
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
De instellingen in detail
Instructies (systeem-prompt)
Het veld instructions komt overeen met de systeem-prompt in de tekst-API’s: het definieert de persoonlijkheid, context en beperkingen van uw voice-agent. Het schrijven hiervan kent echter een specifieke beperking voor spraak: beknoptheid. Elke token van de prompt wordt verwerkt voordat het eerste antwoord wordt gegenereerd; een uitweidende prompt veroorzaakt merkbare latentie zodra het gesprek start. Houd het bij de essentie en verplaats details naar uw applicatielogica. Binnen dit krappe budget verdienen drie elementen een plek. Ten eerste de toon (formeel, vriendelijk, technisch), omdat de voice-agent uw merk letterlijk in het oor van de klant belichaamt. Ten tweede de taal: specificeer deze (“answer in English”), anders volgt de agent mogelijk de taal van de gebruiker of de vraag. Ten slotte de limieten: wat de agent wel kan doen en, nog belangrijker, wat hij moet weigeren of moet doorsturen naar een mens, omdat een antwoord buiten de scope op de telefoon wordt uitgesproken voordat iemand het kan controleren.
Stem
De instelling voice accepteert een van de 28 ingebouwde stemmen van xAI (per 3 november 2026), die zowel door de voice-agent als door text-to-speech worden gebruikt, of de ID van een aangepaste stem gemaakt met de Custom Voices API. Stem-ID’s zijn hoofdlettergevoelig: eve, Eve en EVE verwijzen allemaal naar dezelfde stem. Elke stem spreekt alle ondersteunde talen.
De vijf originele stemmen, zoals beschreven door xAI:
- eve: energiek en opgewekt, Brits accent
- ara: warm en vriendelijk
- rex: zelfverzekerd en helder
- sal: vloeiend en gebalanceerd
- leo: autoritair en krachtig, Brits accent
Daar komen drieëntwintig nieuwere stemmen bij: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora en liora. U kunt de huidige lijst opvragen, inclusief de toon en use cases per stem, via GET /v1/tts/voices of op de xAI-pagina Text to Speech.
Tools
De array tools definieert de tools die de agent tijdens het gesprek kan aanroepen. U kunt verschillende typen combineren: web search, X search, aangepaste functies, RAG-collecties en MCP-servers. De volgende lessen behandelen tools in detail.
Audioconfiguratie
Het object audio stelt de input- en outputformaten in. U kunt verschillende formaten gebruiken voor input en output als uw architectuur daarom vraagt (bijvoorbeeld G.711 ontvangen van een telefoonsysteem en PCM verzenden naar een browser).
De sessie bijwerken tijdens een gesprek
U kunt session.update meerdere keren tijdens een gesprek verzenden. Hiermee kunt u het gedrag van de agent dynamisch wijzigen:
// De stem halverwege het gesprek wijzigen
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Een extra tool toevoegen
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
De documentatie van xAI ondersteunt expliciet wijzigingen tijdens een sessie voor verschillende instellingen (transcriptietaal, trefwoorden, uitspraakvervangingen, audiotransport), en session.updated bevestigt deze wijzigingen: controleer dit event om toe te passen welke configuratie is toegepast.
Belangrijkste punten
session.updateis het eerste bericht dat u nasession.createdverzendt- Het veld
instructionsdefinieert de persoonlijkheid en beperkingen van de agent - Er zijn 28 ingebouwde stemmen beschikbaar (waaronder eve, ara, rex, sal en leo), plus aangepaste stemmen
- Audioconfiguratie en tools zijn aanpasbaar
- U kunt
session.updatemeerdere keren verzenden om het gedrag tijdens een gesprek te wijzigen