Configure the session with session.update

Updated November 3, 2026, based on the xAI Speech to Speech and Text to Speech pages: 28 built-in voices, and turn_detection set by its type alone (with optional idle_timeout_ms). Sources: Speech to Speech · Text to Speech.

Configure your voice agent

Once the WebSocket connection is open and you’ve received the session.created event, configure the session by sending a session.update message. This is where you define how your voice agent behaves: its personality, its voice, the tools it can use, and how it detects turns.

The full structure of session.update

Here’s a detailed configuration example:

{
  "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}
      }
    }
  }
}

The settings in detail

Instructions (system prompt)

The instructions field is the equivalent of the system prompt in the text APIs: it defines your voice agent’s personality, context, and constraints. Writing it comes with a constraint specific to voice, though: brevity. Every token of the prompt is processed before the first response, and a sprawling prompt costs you noticeable latency the moment the call connects. Stick to the essentials and move the details into your application logic. Within that tight budget, three things deserve a place. The tone (formal, friendly, technical), because the voice agent literally embodies your brand in the customer’s ear. The language: specify it (“answer in English”), or the agent may follow the language of the user or the question. And the limits: what the agent can do and, above all, what it must refuse or hand off to a human, because on the phone an out-of-scope answer goes out before anyone can review it.

Voice

The voice setting accepts one of xAI’s 28 built-in voices (as of November 3, 2026), shared by the voice agent and text-to-speech, or the ID of a custom voice created with the Custom Voices API. Voice IDs are case-insensitive: eve, Eve, and EVE all refer to the same voice. Every voice speaks every supported language.

The five original voices, as xAI describes them:

• eve: energetic and upbeat, British accent
• ara: warm and friendly
• rex: confident and clear
• sal: smooth and balanced
• leo: authoritative and powerful, British accent

Twenty-three newer voices join them: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora, and liora. You can get the current list, with each voice’s tone and use cases, from GET /v1/tts/voices or on the xAI Text to Speech page.

Tools

The tools array defines the tools the agent can call during the conversation. You can combine several types: web search, X search, custom functions, RAG collections, and MCP servers. The following lessons cover tools in detail.

Audio configuration

The audio object sets the input and output formats. You can use different formats for input and output if your architecture calls for it (for example, receiving G.711 from a phone system and sending PCM to a browser).

Update the session mid-conversation

You can send session.update several times during a conversation. That lets you change the agent’s behavior on the fly:

// Change the voice mid-conversation
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "Ara"
  }
}));

// Add another tool
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      { type: "web_search" },
      { type: "x_search" }
    ]
  }
}));

The xAI documentation explicitly supports mid-session changes for several settings (transcription language, keywords, pronunciation replacements, audio transport), and session.updated acknowledges them: check it to confirm the configuration that was applied.

Key takeaways

• session.update is the first message to send after session.created
• The instructions field defines the agent’s personality and constraints
• 28 built-in voices are available (including eve, ara, rex, sal, and leo), plus custom voices
• Audio configuration and tools are customizable
• You can send session.update several times to change behavior mid-conversation