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

Dynamic variables support three value types:

System dynamic variables

Your agent has access to built-in system__* variables in every conversation without runtime configuration. These variables are prefixed with the reserved system__ namespace and update automatically as the conversation progresses. Custom dynamic variables cannot use the system__ prefix or override system variables.

Variables marked with † change between turns. Placing them in prompt text can prevent prompt caching; see Best practices for alternatives.

Agent and conversation identity

Time and timezone

Telephony and messaging

These variables are populated when applicable for telephony and messaging channels:

Per-turn conversation state

Conversation history format

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

{
  "x-elevenlabs-history": true,
  "entries": [
    { "role": "user", "message": "Hello" },
    { "role": "agent", "message": "Hi, how can I help?" },
    {
      "role": "agent",
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
    },
    {
      "role": "tool",
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
    }
  ]
}

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 (such as [conversation_history (5 turns)]) to avoid unbounded recursive expansion.

This variable is useful for passing conversation context to tools (such as webhooks or 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 ElevenAgents that they 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.

Use secret dynamic variables for auth tokens or private IDs that should not be sent to an LLM. To create a secret dynamic variable, 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 paths 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

{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}

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

Assignments are configured on each webhook tool; see tool assignments in the API reference.

Guide

Prerequisites:

• An ElevenLabs account
• A configured ElevenAgents agent (follow the quickstart to create one)

import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
dynamic_vars = {
    "user_name": "Angelo",
}
config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)
conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment the below if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
)
conversation.start_session()
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=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

The vars parameter contains base64-encoded JSON:

{ "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=agent_7101k5zvyjhmfg983brhmhkd98n6&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=agent_7101k5zvyjhmfg983brhmhkd98n6&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

// Method 1: Base64-encoded JSON
function generateTalkToURL(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const encodedVars = btoa(JSON.stringify(variables));
  return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
}
// Method 2: Individual parameters
function generateTalkToURLWithParams(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const params = new URLSearchParams({ agent_id: agentId });
  Object.entries(variables).forEach(([key, value]) => {
    params.append(`var_${key}`, encodeURIComponent(value));
  });
  return `${baseURL}?${params.toString()}`;
}
// Usage
const variables = {
  user_name: "John Doe",
  account_type: "premium",
  session_id: "sess_123"
};
const urlMethod1 = generateTalkToURL("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
const urlMethod2 = generateTalkToURLWithParams("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);

Best practices

Troubleshooting