Dynamic variables: personalize Retell agent calls

​

Overview

​

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

• 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 URLs: Both agent-level (webhook_url) and account-level webhook URLs support dynamic variables, so you can route events per call (for example, https://example.com/webhook?call_for={{customer_name}}).

​

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?"

Supported fields include a variable picker so you do not have to remember exact names:

1. Type {{ where you want a variable. A dropdown opens listing variables that apply in that context (for example, default system variables plus variables defined for the agent or flow).
2. Filter the list by typing more characters after {{.
3. Choose a variable with Enter, a click, or Tab. The editor inserts the full placeholder and closes the braces, for example {{customer_name}}.

You can still type {{variable_name}} by hand in supported fields. The picker is optional.

2

Test your dynamic variables

Before deploying, test your dynamic variables using the web interface. You can also set test values for each variable in a simulation test case, so automated test runs resolve placeholders the same way real calls do.

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

​

Phone Call Variables

​

Chat Variables

​

Contact Variables

​

Nested Variables

{{current_time_{{my_timezone}} }}

​

Handling Missing Variables

​

Default Behavior

• 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)

Equation: {{user_name}} exists
Result: True if variable is defined (even an empty string is considered having a value)

​

In Prompts

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

• 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