Dynamic variables

Pass runtime values to personalize your agent's behavior.

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 and headers 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
  • Accessing system information like conversation ID or call duration

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

System dynamic variables

Your agent has access to these automatically available system variables:

  • system__agent_id - Unique identifier of the agent that initiated the conversation (stays stable throughout the conversation)
  • system__current_agent_id - Unique identifier of the currently active agent (changes after agent transfers)
  • system__caller_id - Caller’s phone number (voice calls only)
  • system__called_number - Destination phone number (voice calls only)
  • system__call_duration_secs - Call duration in seconds
  • system__time_utc - Current UTC time (ISO format)
  • system__conversation_id - ElevenLabs’ unique conversation identifier
  • system__call_sid - Call SID (twilio calls only)

System variables:

  • Are available without runtime configuration
  • Are prefixed with system__ (reserved prefix)
  • In system prompts: Set once at conversation start (value remains static)
  • In tool calls: Updated at execution time (value reflects current state)
Custom dynamic variables cannot use the reserved system__ prefix.

Secret dynamic variables

Secret dynamic variables are populated in the same way as normal dynamic variables but indicate to our Conversational AI platform that these should only be used in dynamic variable headers and never sent to an LLM provider as part of an agent’s system prompt or first message.

We recommend using these for auth tokens or private IDs that should not be sent to an LLM. To create a secret dynamic variable, simply prefix the dynamic variable with secret__.

Updating dynamic variables from tools

Tool calls can create or update dynamic variables if they return a valid JSON object. To specify what should be extracted, set the object path(s) using dot notation. If the field or path doesn’t exist, nothing is updated.

Example of a response object and dot notation:

  • Status corresponds to the path: response.status
  • The first user’s email in the users array corresponds to the path: response.users.0.email
JSON
1{
2 "response": {
3 "status": 200,
4 "message": "Successfully found 5 users",
5 "users": [
6 "user_1": {
7 "user_name": "test_user_1",
8 "email": "test_user_1@email.com"
9 }
10 ]
11 }
12}

To update a dynamic variable to be the first user’s email, set the assignment like so.

Query parameters

Assignments are a field of each server tool, that can be found documented here.

Guide

Prerequisites

1

Define dynamic variables in prompts

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

  • System prompts
  • First messages
  • Tool parameters

Dynamic variables in messages

Dynamic variables in messages

2

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.

Setting placeholders

Setting placeholders

3

Set placeholders

Configure default values in the web interface for testing:

Setting placeholders

4

Pass variables at runtime

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

Ensure you have the latest SDK installed.

1import os
2import signal
3from elevenlabs.client import ElevenLabs
4from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
5from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
6
7agent_id = os.getenv("AGENT_ID")
8api_key = os.getenv("ELEVENLABS_API_KEY")
9elevenlabs = ElevenLabs(api_key=api_key)
10
11dynamic_vars = {
12 "user_name": "Angelo",
13}
14
15config = ConversationInitiationData(
16 dynamic_variables=dynamic_vars
17)
18
19conversation = Conversation(
20 elevenlabs,
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
35conversation.start_session()
36
37signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

Public Talk-to Page Integration

The public talk-to page supports dynamic variables through URL parameters, enabling you to personalize conversations when sharing agent links. This is particularly useful for embedding personalized agents in websites, emails, or marketing campaigns.

URL Parameter Methods

There are two methods to pass dynamic variables to the public talk-to page:

Method 1: Base64-Encoded JSON

Pass variables as a base64-encoded JSON object using the vars parameter:

https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

The vars parameter contains base64-encoded JSON:

1{ "user_name": "John", "account_type": "premium" }

Method 2: Individual Query Parameters

Pass variables using var_ prefixed query parameters:

https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&var_user_name=John&var_account_type=premium

Parameter Precedence

When both methods are used simultaneously, individual var_ parameters take precedence over the base64-encoded variables to prevent conflicts:

https://elevenlabs.io/app/talk-to?agent_id=your_agent_id&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John

In this example, user_name will be “John” (from var_user_name) instead of “Jane” (from the base64-encoded vars).

Implementation Examples

1// Method 1: Base64-encoded JSON
2function generateTalkToURL(agentId, variables) {
3 const baseURL = 'https://elevenlabs.io/app/talk-to';
4 const encodedVars = btoa(JSON.stringify(variables));
5 return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
6}
7
8// Method 2: Individual parameters
9function generateTalkToURLWithParams(agentId, variables) {
10 const baseURL = 'https://elevenlabs.io/app/talk-to';
11 const params = new URLSearchParams({ agent_id: agentId });
12
13 Object.entries(variables).forEach(([key, value]) => {
14 params.append(`var_${key}`, encodeURIComponent(value));
15 });
16
17 return `${baseURL}?${params.toString()}`;
18}
19
20// Usage
21const variables = {
22 user_name: "John Doe",
23 account_type: "premium",
24 session_id: "sess_123"
25};
26
27const urlMethod1 = generateTalkToURL("your_agent_id", variables);
28const urlMethod2 = generateTalkToURLWithParams("your_agent_id", variables);

Supported Types

Dynamic variables support these value types:

String
Text values
Number
Numeric values
Boolean
True/false values

Troubleshooting

Verify that:

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

Ensure that:

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