Skip to main content

​
Overview

Dynamic variables hold values your agent can use during a call or chat. Write {{variable_name}} in a supported field, and Retell replaces it with the value available when that field is used. For example, pass customer_name when starting a call and use Hello {{customer_name}} in the opening message. The same variable can be used later in a tool request.

​
Where dynamic variables work

In a code tool or code node, read variables through dv.variable_name rather than inserting {{variable_name}} into JavaScript.

​
Add & test dynamic variables

1

Add dynamic variables in your prompts

Dynamic variables are placeholders surrounded by double curly braces. For example:
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

Set agent-level defaults for values the agent should use when no other source supplies them. See where values come from for how defaults interact with other values.
4

Implement in production

Outbound calls: Set your variables in the retell_llm_dynamic_variables field of the Create Phone Call request. Use strings for all values:
Inbound calls: Supply variables through the Inbound Call Webhook.Web calls and chats: Pass retell_llm_dynamic_variables when creating a web call or chat.Custom telephony: Pass retell_llm_dynamic_variables to Register Phone Call.Batch calls: Add a CSV column for each variable so each recipient gets their own values. See batch calls.
Send values in retell_llm_dynamic_variables as strings, as required by the API schema. For example, send a number as "42" or a boolean as "true". In code tools, convert values before using them: Number(dv.order_count) turns a numeric string into a number.
The spaces around the variable name will be trimmed when evaluating the variable.

​
Where values come from

You can supply values before a conversation starts or collect them while it runs. An Extract Dynamic Variable tool saves information from the conversation. Tool response mappings save values returned by your systems. Later prompts and tools can use those values without another lookup. When the same name appears in more than one source, the sources below take precedence from top to bottom: a lower row overrides a higher row. For example, if an agent default sets customer_name to there, passing customer_name: "Sam" in the call request makes Hello {{customer_name}} become Hello Sam. If an extraction tool later saves a corrected name, subsequent uses receive that value.

​
Default system variables

Retell automatically provides these system variables - no configuration required:
To choose the timezone for a particular call, pass system_timezone as a dynamic variable, such as "Australia/Sydney". Time variables with a timezone in their name, such as {{current_time_Australia/Sydney}}, always use that timezone.

​
Call variables

These variables are available for both phone calls and web calls:

​
Phone call variables

​
Chat Variables

Chat sessions provide a chat ID and, when available, the user’s phone number:

​
Post-conversation Variables

These variables exist only after the session ends, so only a post-call or post-chat function on the agent’s workflow can read them: {{call_summary}}, {{call_successful}}, {{user_sentiment}}, {{disconnection_reason}}, {{call_status}}, and one variable per custom Post Call Extraction field, named after the field. On chat agents the first two are {{chat_summary}} and {{chat_successful}}, and the status is {{chat_status}}.

​
Contact Variables

When a phone call or SMS chat matches a contact by phone number, that contact’s fields are passed in as variables automatically. You get {{first_name}}, {{last_name}}, {{do_not_call}}, {{contact_memory}} when stored, and one variable per custom contact field, named after the field. Nothing is passed when no contact matches, so write the prompt to read correctly without them. Built-in contact memory holds a running brief of past conversations. Enable Use contact memory on the agent to add that brief to its context automatically; you don’t need to reference the variable explicitly. Custom contact fields still use their own extraction mappings.

​
Nested Variables

Retell supports nested variables. You can use the following syntax to create nested variables:
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.
Nested variables refer to variable-inside-variable substitution, not access to nested JSON properties. Because every value must be a string, you can’t pass an object like {"client": {"name": "Mario"}} and reference {{client.name}}. Flatten the object into individual string variables instead, for example {"client_name": "Mario"} referenced as {{client_name}}.

​
Handling Missing Variables

​
Default Behavior

In prompts and messages, a variable with no assigned value remains in its raw form with the curly braces intact. Assuming no default or other source supplies user_name: Example:
  • Prompt: "Hello {{user_name}}, how can I help you today?"
  • If user_name is not provided (missing key or null): "Hello {{user_name}}, how can I help you today?"
  • If user_name is "" (empty string): "Hello , how can I help you today?" — the placeholder is replaced with nothing
  • If user_name is "John": "Hello John, how can I help you today?"
An empty string counts as a value. Pass "" to replace the placeholder with nothing. Omit the key or pass null to let a lower-priority source, such as an agent default, supply the value.

​
Checking for Unset Variables

​
In Conversation Flow (Equations)

To check if a variable is set in conversation flow conditions:

​
In Prompts

To handle unset variables in your prompts, you can add conditional logic:

​
Best Practices for Missing Variables

  1. Set defaults at agent level: Configure Default Dynamic Variables under Security & fallback settings in the agent editor
  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