​
Overview

Dynamic variables are a special syntax that allow you to inject data into various parts of the agents for specific call.

They allow you to personalize your agent’s responses while keeping the core conversation flow intact. They’re perfect for customizing greetings, referencing specific information, or adapting responses based on context.

​
Where can I use them?

  • prompt
  • begin message
  • tool call description
  • custom tool call properties description
  • voicemail setting (both prompt and static text)
  • transfer call function number: in case you want to transfer call to a dynamic number
  • warm transfer setting (both prompt and static text)

​
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

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 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.

​
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”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”
{{call_type}}Call type, web_call or phone_call”phone_call”

These variables are only available for phone calls:

VariableDescriptionExample
{{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”

​
Edge Cases

When a dynamic variable is not assigned a value, it will remain unchanged in the output. For example:

  • Original prompt: "Hello {{user_name}}, how can I help you today?"
  • Output when user_name is not set: "Hello {{user_name}}, how can I help you today?"

This means missing variables will be visible in their raw form ({{variable_name}}) rather than being replaced with an empty string or causing an error.

​
🎦 Video Tutorial

See community templates in docs