Skip to main content

​
Overview

Dynamic variables allow you to inject personalized data into your agent’s responses for each specific call. Using the {{variable_name}} syntax, you can create agents that adapt to different contexts while maintaining consistent conversation flows.

​
Common Use Cases

  • Personalized greetings: “Hello {{customer_name}}, thanks for calling!”
  • Context-aware responses: “I see you’re calling about order {{order_id}}”
  • Dynamic routing: Transfer to different numbers based on {{department}}
  • Time-sensitive information: Reference {{appointment_date}} or {{deadline}}

​
Where Dynamic Variables Work

Dynamic variables can be used in:
  • Prompts: Agent instructions and personality
  • Begin message: Opening greeting
  • Tool configurations:
    • Custom function URLs
    • Tool descriptions
    • Property descriptions
  • Call handling:
    • Voicemail prompts and messages
    • Transfer call phone numbers
    • Warm transfer instructions
  • Webhook url

​
Add & test dynamic variables

1

Add dynamic variables in your prompts

Dynamic variables are placeholders surrounded by double curly braces. For example:
"Hello {{user_name}}, I understand you're interested in {{product_name}}. How can I help you today?"
2

Test your dynamic variables

Before deploying, test your dynamic variables using the web interface
Testing dynamic variables in dashboard
3

Configure agent-level default dynamic variables

You can set default values for dynamic variables at the agent level. Default variables serve as a fallback and will only be used when specific variables aren’t included in the call request.
Testing dynamic variables in dashboard
4

Implement in production

​
For Outbound Calls

When using the Create Phone Call API, set your variables in the retell_llm_dynamic_variables field. Note that all values must be strings:
{
    "user_name": "John Smith",
    "product_name": "Premium Plan",
    "account_status": "active"
}

​
For Inbound Calls

You can supply dynamic variables in the Inbound Call Webhook. More details are at the linked doc.
Important: All values in retell_llm_dynamic_variables must be strings. Numbers, booleans, or other data types are not supported.
The spaces around the variable name will be trimmed when evaluating the variable.

​
Default System Variables

Retell automatically provides these system variables - no configuration required:
VariableDescriptionExample
{{current_agent_state}}Current state name (for multi-state agents)“greeting”
{{previous_agent_state}}Previous state name (for multi-state agents)“qualification”
{{current_time}}Current time in America/Los_Angeles”Thursday, March 28, 2024 at 11:46:04 PM PST”
{{current_time_[timezone]}}Current time in specified timezone, for example: {{current_time_Australia/Sydney}}”Thursday, March 28, 2024 at 11:46:04 PM AEDT”
{{current_calendar}}14-day calendar in America/Los_Angeles”Thursday, March 28, 2024 PST (Today)
Friday, March 29, 2024 PST
…
Wednesday, April 10, 2024 PST”
{{current_calendar_[timezone]}}14-day calendar in specified timezone, for example: {{current_calendar_Australia/Sydney}}”Thursday, March 28, 2024 AEDT (Today)
Friday, March 29, 2024 AEDT
…
Wednesday, April 10, 2024 AEDT”
{{session_type}}Session type, voice or chatvoice
{{session_duration}}How long the session has been running, available after call / chat starts20 minutes 30 seconds

​
Phone Call Variables

These variables are only available for phone calls:
VariableDescriptionExample
{{direction}}Call direction, inbound or outboundinbound
{{user_number}}User’s phone number (from_number for inbound, to_number for outbound)+12137771234
{{agent_number}}Agent’s phone number (to_number for inbound, from_number for outbound)+12137771235
{{call_id}}Current call session idcall_12345678906eaa0222bd3dd2a6c
{{call_type}}Call type, web_call or phone_call”phone_call”

​
Chat Variables

These variables are only available for chat sessions:
VariableDescriptionExample
{{chat_id}}The unique identifier for the current chat sessionchat_12345678906eaa0222bd3dd2a6c

​
Nested Variables

Retell supports nested variables, you can use the following syntax to create nested variables: 
{{current_time_{{my_timezone}} }}
Now if you have set my_timezone to America/Los_Angeles, this would evaluate to {{current_time_America/Los_Angeles }} first, and will then evaluate to the actual time, as this is a system default variable.

​
Handling Missing Variables

​
Default Behavior

When a dynamic variable has no assigned value, it remains in its raw form with the curly braces intact: Example:
  • Prompt: "Hello {{user_name}}, how can I help you today?"
  • If user_name is not provided: "Hello {{user_name}}, how can I help you today?"
  • If user_name is “John”: "Hello John, how can I help you today?"

​
Checking for Unset Variables

​
In Conversation Flow (Equations)

To check if a variable is set in conversation flow conditions: 
Equation: {{user_name}} exists
Result: True if variable is set

​
In Prompts

To handle unset variables in your prompts, you can add conditional logic: 
If {{user_name}} appears with curly braces, use a generic greeting.
Otherwise, greet the customer by name.

​
Best Practices for Missing Variables

  1. Set defaults at agent level: Configure fallback values in agent settings
  2. Use defensive prompting: Design prompts that work with or without variables
  3. Test thoroughly: Always test with both set and unset variables
  4. Document requirements: Clearly indicate which variables are required vs optional

​
🎦 Video Tutorial

​
Additional Resources