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
Add & test dynamic variables
1
Add dynamic variables in your prompts
Dynamic variables are placeholders surrounded by double curly braces. For example:
2
Test your dynamic variables
Before deploying, test your dynamic variables using the web interface

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.

4
Implement in production
For Outbound Calls
When using the Create Phone Call API, set your variables in theretell_llm_dynamic_variables
field. Note that all values must be strings: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.
Default System Variables
Retell automatically provides these system variables - no configuration required:Variable | Description | Example |
---|---|---|
{{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 chat | voice |
Phone Call Variables
These variables are only available for phone calls:Variable | Description | Example |
---|---|---|
{{direction}} | Call direction, inbound or outbound | inbound |
{{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 id | call_12345678906eaa0222bd3dd2a6c |
{{call_type}} | Call type, web_call or phone_call | ”phone_call” |
Chat Variables
These variables are only available for chat sessions:Variable | Description | Example |
---|---|---|
{{chat_id}} | The unique identifier for the current chat session | chat_12345678906eaa0222bd3dd2a6c |
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 unset in conversation flow conditions:In Prompts
To handle unset variables in your prompts, you can add conditional logic:Best Practices for Missing Variables
- Set defaults at agent level: Configure fallback values in agent settings
- Use defensive prompting: Design prompts that work with or without variables
- Test thoroughly: Always test with both set and unset variables
- Document requirements: Clearly indicate which variables are required vs optional
🎦 Video Tutorial
Additional Resources
- Community Templates: Examples and patterns from the Retell community
- API Reference: Full documentation on passing dynamic variables
- Inbound Webhook Guide: Setting variables for incoming calls