Dynamic Variables

During different calls, it’s a common need to personalize some portion of the setup but keep the rest intact. This is where dynamic variables come in. You can use this to customize for every call you make.

​

Where Can I Use It

You can use it almost everywhere in the LLM setup that involves string. Here are some places where you can use dynamic variables:

• Prompts: General Prompt, State Prompt
• Begin Message
• Tool Call Description: General Tool Call Description, State Tool Call Description

​

Define Dynamic Variables

Defining a dynamic variable is simple, you just have to wrap two curly braces around the variable name. Check the example below:

"Current time is {{current_time}}, the user name is {{user_name}}, user email is {{user_email}}."

This string references four dynamic variables: current_time, user_name, user_email.

​

Populate Value of Dynamic Variables

We have gone through how to define dynamic variables, now let’s see how the value of these variables are populated to be used to customize. There are three categories how the value of dynamic variables are populated:

​

Default Variables

These are variables that are always available in the system, you don’t have to pass them, we will set it for you. You can directly reference them in your prompt, begin message, or tool call description.

• current_agent_state: the name of current state (if LLM has states).
• previous_agent_state: the name of previous state (if LLM has states and have transitioned).
• current_time: the current time string in the format like Thursday, March 28, 2024 at 11:46:04 PM PST

​

Populate When Starting The Call

Most common place to populate dynamic variables is when you are starting the call. A lot of time it’s retrieved and set based on customer / user data associated with the number.

​

Outbound Phone Calls With Retell Numbers

Set retell_llm_dynamic_variables field in Create Phone Call API.

​

Inbound Phone Calls With Retell Numbers

Set inbound_dynamic_variables_webhook_url field in Create Retell LLM API. This way Retell server would POST to your webhook URL when inbound phone call happens, and your webhook shall return the dynamic variable key value pairs. This is designed as a webhook because for inbound calls, it’s not initiated from your system, so you can’t set the dynamic variable key value beforehand.

To identify user and customize dynamic variables, we would pass the following properties in the body of POST request.

{
  "llm_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "from_number": "+12137771234",
  "to_number": "+12137771235"
}

You need to return the dynamic variable key value pairs in the response body as JSON. Here is an example response:

{
  "user_name": "John Doe",
  "user_email": "john@example.com"
}

​

Phone Calls With Your Own Numbers (Custom Twilio)

Set retell_llm_dynamic_variables field in Register Call API. This API is likely called in your Twilio voice webhook.

​

Web Calls

Set retell_llm_dynamic_variables field in Register Call API. This API is likely called from your backend that connects with your frontend.

​

Populate When Transitioning Between States (During Call)

Read more about this in Define LLM States.