Dynamic variables — ElevenLabs Documentation

Dynamic variables allow you to inject runtime values into your agent’s messages, system prompts, and tools. This enables you to personalize each conversation with user-specific data without creating multiple agents.

Overview

Dynamic variables can be integrated into multiple aspects of your agent:

System prompts to customize behavior and context
First messages to personalize greetings
Tool parameters to pass user-specific data

Here are a few examples where dynamic variables are useful:

Personalizing greetings with user names
Including account details in responses
Passing data to tool calls
Customizing behavior based on subscription tiers

Dynamic variables are ideal for injecting user-specific data that shouldn’t be hardcoded into your agent’s configuration.

Guide

Prerequisites

An ElevenLabs account
A configured ElevenLabs Conversational Agent (create one here)

Define dynamic variables in prompts

Add variables using double curly braces {{variable_name}} in your:

System prompts
First messages
Tool parameters

Define dynamic variables in tools

You can also define dynamic variables in the tool configuration. To create a new dynamic variable, set the value type to Dynamic variable and click the + button.

Set placeholders

Configure default values in the web interface for testing:

Pass variables at runtime

When starting a conversation, provide the dynamic variables in your code:

Ensure you have the latest SDK installed.

1 import os
2 import signal
3 from elevenlabs.client import ElevenLabs
4 from elevenlabs.conversational_ai.conversation import Conversation, ConversationConfig
5 from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
6 
7 agent_id = os.getenv("AGENT_ID")
8 api_key = os.getenv("ELEVENLABS_API_KEY")
9 client = ElevenLabs(api_key=api_key)
10 
11 dynamic_vars = {
12   "user_name": "Angelo",
13 }
14 
15 config = ConversationConfig(
16   dynamic_variables=dynamic_vars
17 )
18 
19 conversation = Conversation(
20   client,
21   agent_id,
22   config=config,
23   # Assume auth is required when API_KEY is set.
24   requires_auth=bool(api_key),
25   # Use the default audio interface.
26   audio_interface=DefaultAudioInterface(),
27   # Simple callbacks that print the conversation to the console.
28   callback_agent_response=lambda response: print(f"Agent: {response}"),
29   callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
30   callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
31   # Uncomment the below if you want to see latency measurements.
32   # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
33 )
34 
35 conversation.start_session()
36 
37 signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

Supported Types

Dynamic variables support these value types:

String

Text values

Number

Numeric values

Boolean

True/false values

Troubleshooting

Variables not replacing

Verify that:

Variable names match exactly (case-sensitive)
Variables use double curly braces: {{ variable_name }}
Variables are included in your dynamic_variables object

Type errors

Ensure that:

Variable values match the expected type
Values are strings, numbers, or booleans only

1	import os
2	import signal
3	from elevenlabs.client import ElevenLabs
4	from elevenlabs.conversational_ai.conversation import Conversation, ConversationConfig
5	from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
6
7	agent_id = os.getenv("AGENT_ID")
8	api_key = os.getenv("ELEVENLABS_API_KEY")
9	client = ElevenLabs(api_key=api_key)
10
11	dynamic_vars = {
12	"user_name": "Angelo",
13	}
14
15	config = ConversationConfig(
16	dynamic_variables=dynamic_vars
17	)
18
19	conversation = Conversation(
20	client,
21	agent_id,
22	config=config,
23	# Assume auth is required when API_KEY is set.
24	requires_auth=bool(api_key),
25	# Use the default audio interface.
26	audio_interface=DefaultAudioInterface(),
27	# Simple callbacks that print the conversation to the console.
28	callback_agent_response=lambda response: print(f"Agent: {response}"),
29	callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
30	callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
31	# Uncomment the below if you want to see latency measurements.
32	# callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
33	)
34
35	conversation.start_session()
36
37	signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())