​
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

Implement in production

For Outbound Calls

When using the Create Phone Call API, set your variables in the retell_llm_dynamic_variables field:

{
  "user_name": "John Smith",
  "product_name": "Premium Plan",
  "account_status": "active"
}

For Inbound Calls

  1. Set up a webhook URL in Create Retell LLM API using the inbound_dynamic_variables_webhook_url field
  2. Configure your webhook to handle POST requests with the following payload:
{
  "llm_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "from_number": "+12137771234",
  "to_number": "+12137771235"
}
  1. Return dynamic variables in your response:
{
  "user_name": "John Doe",
  "user_email": "john@example.com"
}

​
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 timestamp with timezone”Thursday, March 28, 2024 at 11:46:04 PM PST”

​
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

Was this page helpful?

Knowledge BaseBest Practices