Dynamic variables

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

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__time - Current time in the specified timezone (human-readable format, e.g., “Friday, 12:33 12 December 2025”)
• system__timezone - User-provided timezone (must be valid for tzinfo)
• system__conversation_id - ElevenLabs’ unique conversation identifier
• system__call_sid - Call SID (twilio calls only)
• system__agent_turns - The total number of conversation turns the agent has taken during this conversation.
• system__current_agent_turns - The number of conversation turns the current agent has taken. Resets whenever the conversation transfers to a different agent.
• system__current_subagent_turns - The number of conversation turns the current subagent has taken. Resets whenever the workflow transitions to a different node.
• system__is_text_only - True if the conversation operates in text-only mode, false otherwise.
• system__conversation_history - JSON-serialized representation of the current conversation history. Lazily evaluated at the moment it is referenced. See format details below.

System variables:

• Are available without runtime configuration
• Are prefixed with system__ (reserved prefix)
• Are updated automatically throughout the conversation

Conversation history format

The system__conversation_history variable contains a JSON object with the following structure:

1
{
2
  "x-elevenlabs-history": true,
3
  "entries": [
4
    { "role": "user", "message": "Hello" },
5
    { "role": "agent", "message": "Hi, how can I help?" },
6
    {
7
      "role": "agent",
8
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
9
    },
10
    {
11
      "role": "tool",
12
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
13
    }
14
  ]
15
}

Each entry includes a role ("user", "agent", or "tool") and one of:

• message — the text content of the turn
• tool_requests — an array of tool calls made by the agent, with resolved parameter values
• tool_results — an array of tool responses

If a tool result or parameter contains a nested conversation history, it is redacted to a placeholder (e.g. [conversation_history (5 turns)]) to avoid unbounded recursive expansion.

This variable is useful for passing conversation context to tools (e.g. webhooks, custom LLMs) or for including conversation history in sub-agent prompts during handoffs.

Secret dynamic variables

Secret dynamic variables are populated in the same way as normal dynamic variables but indicate to our ElevenAgents 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

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.

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

Guide

Prerequisites

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

1
import os
2
import signal
3
from elevenlabs.client import ElevenLabs
4
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
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
elevenlabs = ElevenLabs(api_key=api_key)
10
11
dynamic_vars = {
12
    "user_name": "Angelo",
13
}
14
15
config = ConversationInitiationData(
16
    dynamic_variables=dynamic_vars
17
)
18
19
conversation = 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
35
conversation.start_session()
36
37
signal.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
2
function 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
9
function 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
21
const variables = {
22
  user_name: "John Doe",
23
  account_type: "premium",
24
  session_id: "sess_123"
25
};
26
27
const urlMethod1 = generateTalkToURL("your_agent_id", variables);
28
const urlMethod2 = generateTalkToURLWithParams("your_agent_id", variables);

Supported Types

Dynamic variables support these value types:

Troubleshooting