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:
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:ws.on("open", () => {
ws.send(JSON.stringify({
type: "conversation_initiation_client_data",
dynamic_variables: {
company_name: "Acme Corp",
user_name: "Jordan",
plan_name: "Pro",
},
}));
});
Pass variables when generating the conversation token on your server: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
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
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:
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.
