Personalize each conversation with variables and overrides

Personalization lets you tailor every conversation to the individual user without creating a separate agent for each use case. You pass data at conversation start, and the platform substitutes it into the system prompt or applies it as a configuration override before the first exchange.

Dynamic variables

Dynamic variables are placeholders in your system prompt that the platform replaces with real values at the start of each session. Use them to inject user-specific information — names, account tiers, preferences, or any other data your backend holds.

Syntax

Wrap variable names in double curly braces:

system-prompt.txt

You are a support agent for {{company_name}}.

The user's name is {{user_name}} and they are on the {{plan_name}} plan.
If they are on the Pro plan, they qualify for priority support.

Passing variable values

Pass variable values when initiating the conversation. The exact method depends on whether you are using signed URLs, conversation tokens, or the WebSocket API directly.

Signed URL / WebSocket
Conversation token

Pass variables in the conversation_initiation_client_data message immediately after the WebSocket connection is established:

client.js

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "conversation_initiation_client_data",
    dynamic_variables: {
      company_name: "Acme Corp",
      user_name: "Jordan",
      plan_name: "Pro",
    },
  }));
});

If you are using the React SDK, pass dynamic variables when generating the conversation token on your server instead (see the Conversation token tab).

Pass variables when generating the conversation token on your server:

server.py

from xuna_ai import XunaAI

client = XunaAI()

response = client.conversational_ai.conversations.get_token(
    agent_id="your-agent-id",
    dynamic_variables={
        "company_name": "Acme Corp",
        "user_name": "Jordan",
        "plan_name": "Pro",
    }
)
token = response.token

Do not pass sensitive data (passwords, payment card numbers, SSNs) as dynamic variables. Variable values appear in the conversation context and may be logged. Use server tools to look up sensitive data at runtime instead.

Session overrides

In addition to dynamic variables, you can override core agent settings for a specific session. Overrides do not change the agent’s default configuration — they apply only to the conversation being started.

Supported overrides

Override	Description
`voice_id`	Replace the agent’s default voice with a different one for this session.
`prompt`	Replace the entire system prompt for this session.
`language`	Set a different language for ASR and TTS for this session.

Applying overrides

Conversation token (Python)
Conversation token (TypeScript)

server.py

from xuna_ai import XunaAI

client = XunaAI()

response = client.conversational_ai.conversations.get_token(
    agent_id="your-agent-id",
    conversation_config_override={
        "agent": {
            "prompt": {
                "prompt": "You are a Spanish-language support agent for Acme Corp."
            },
            "language": "es",
        },
        "tts": {
            "voice_id": "different-voice-id-for-spanish",
        }
    }
)
token = response.token

server.ts

import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

const client = new XunaAIClient();

const response = await client.conversationalAi.conversations.getToken({
  agentId: "your-agent-id",
  conversationConfigOverride: {
    agent: {
      prompt: {
        prompt: "You are a Spanish-language support agent for Acme Corp.",
      },
      language: "es",
    },
    tts: {
      voiceId: "different-voice-id-for-spanish",
    },
  },
});
const token = response.token;

Combining variables and overrides

You can use dynamic variables and overrides together. A common pattern is to use variables for user data and overrides for locale-specific configuration:

server.py

from xuna_ai import XunaAI

client = XunaAI()

response = client.conversational_ai.conversations.get_token(
    agent_id="your-agent-id",
    dynamic_variables={
        "user_name": user.name,
        "account_balance": str(user.account_balance),
    },
    conversation_config_override={
        "agent": {
            "language": user.preferred_language,
        },
        "tts": {
            "voice_id": voice_id_for_locale(user.preferred_language),
        }
    }
)
token = response.token

Store voice IDs and prompt variants in your database keyed by locale or persona. At session start, look up the right values and pass them as overrides. This keeps your agent logic in code and your agent configuration minimal.

Get Started

Configure

Deploy

Monitor & Optimize

Personalize each conversation with variables and overrides

Dynamic variables

Syntax

Passing variable values

Session overrides

Supported overrides

Applying overrides

Combining variables and overrides

​Dynamic variables

​Syntax

​Passing variable values

​Session overrides

​Supported overrides

​Applying overrides

​Combining variables and overrides

Dynamic variables

Syntax

Passing variable values

Session overrides

Supported overrides

Applying overrides

Combining variables and overrides