Dynamic Variables in DialNexa Agents - DialNexa Documentation

Dynamic variables in DialNexa are {{variable_name}} placeholders that make one agent behave differently for each caller. Instead of creating separate agents per customer segment, you write one prompt with variables and supply different values at call time. Variables work in prompts, welcome messages, voicemail messages, function parameters, and post-call analysis fields.

Dynamic variables are personalization with a seatbelt. Without fallback defaults, a variable with no value will be spoken literally by the agent. The caller will hear “double brace first underscore name double brace”.

Before You Begin

List the values that change per caller, every surface that supplies them, and safe fallback text for missing data. Do not use secrets or values that should never appear in a transcript.

Syntax

Wrap any variable name in double curly braces:

{{variable_name}}

Variable names are case-sensitive. {{first_name}} and {{First_Name}} are treated as different variables. Use lowercase with underscores for consistency. The builder validates variable syntax in prompt-related fields. Variable names should start with a letter or underscore and can contain letters, numbers, underscores, or dots. Empty variables, unclosed braces, and malformed patterns such as {{amount} } are rejected before save or test call. You can place variables anywhere in a prompt:

You are calling {{first_name}} {{last_name}} at {{company_name}}.
Their subscription renews on {{renewal_date}} and the current balance is {{balance_amount}}.

The agent builder scans the prompt text, welcome message, and voicemail message for placeholders and lists each detected variable in Agent Settings > Fallback Settings, where you can set a default value.

Where Variables Can Be Used

Location	Example usage
System prompt	`You are calling {{first_name}} about their overdue invoice of {{amount_due}}.`
Welcome message	`Hi {{first_name}}, this is Priya from Metro Clinic.`
Voicemail message	`Hi {{first_name}}, please call us back about your appointment on {{appointment_date}}.`
Function parameters	Pass `{{account_id}}` as a parameter to a CRM lookup API call
Post-call analysis field descriptions	`Did {{first_name}} confirm the appointment?`

Built-In Default Variables

DialNexa injects a set of variables automatically for every call. You do not need to pass these manually; they are available in every agent.

Variable	What it contains
`{{caller_number}}`	The phone number that initiated the call (inbound) or the number being dialed (outbound)
`{{call_id}}`	The unique identifier for the call session
`{{agent_id}}`	The ID of the agent handling the call
`{{agent_name}}`	The name of the agent as configured in the workspace

Use {{caller_number}} in prompts to acknowledge the caller’s number, or pass it to a function that looks up the caller in your CRM.

How to Pass Variable Values

Variable values can come from several sources. When multiple sources supply a value for the same variable, the priority order is: API / batch CSV / workflow > test call modal > default fallback.

API (outbound call request)

When starting an outbound call via the DialNexa API, include a variables or metadata object in the request body with key-value pairs matching your variable names.

{
  "agent_id": "...",
  "to": "+919876543210",
  "variables": {
    "first_name": "Rahul",
    "renewal_date": "June 15",
    "balance_amount": "3,200"
  }
}

See the API reference for the exact request schema.

Batch CSV (batch calls)

When creating a batch call campaign, upload a CSV file where each row is one call recipient. Column headers must match the variable names used in the agent.

phone_number,first_name,renewal_date,balance_amount
+919876543210,Rahul,June 15,3200
+919812345678,Anjali,June 18,1450

The batch call engine maps each CSV column to the corresponding variable for that call. See Batch Recipient Files for file format requirements.

Workflow lead variables

In the workflow builder, leads carry their own variable values. When a workflow triggers a call, the lead’s variables are passed to the agent automatically. Variable keys in the lead record must match the variable names in the agent prompt.See Workflow Lead Variables for how to define and map lead variables.

Fallback defaults (Agent Settings)

Default values for each variable are configured in Agent Settings > Fallback Settings. These are used when no other source provides a value for the variable.Fallback defaults are saved as part of the agent version when published. They are the safety net for any call where the upstream data is incomplete.

Setting Fallback Defaults

Open Agent Settings

In the agent builder, click the Settings tab, then navigate to Fallback Settings.

Find detected variables

The builder lists every {{variable_name}} it found in the prompt, welcome message, and voicemail message.

Enter a default value for each variable

Enter a fallback value that is safe to use when the real value is unavailable. For names, a generic fallback like “there” works: “Hi there” instead of “Hi ”. For amounts or dates, use a placeholder that prompts the caller to confirm: “your upcoming appointment”.

Save and include in publish

Save the settings. Fallback values are included in the published version snapshot.

Leaving a fallback default empty does not cause an error on its own, but it means the agent will speak the {{variable_name}} text literally if no value is supplied at call time. Always set a fallback for every variable in your prompt.

Testing Variable Rendering

Before publishing, test that variables render correctly:

Open the agent builder and click the test call button.
In the test call modal, enter values for each variable.
Place the test call and listen to the welcome message and first prompt. Confirm the values appear correctly in speech.
Check the call transcript in Call History to see how variables were rendered in writing.

Variable Mistakes to Avoid

Variable name mismatch between agent and CSV

If the agent uses {{first_name}} but the CSV column is FirstName, the value will not map. Variable names are case-sensitive and must match exactly. Use lowercase underscore convention in both the agent prompt and the CSV header.

Empty fallback value

A variable with no fallback and no runtime value will be spoken literally. The agent builder may warn when saving a version with empty fallbacks. Treat this as a required field, not optional.

Sensitive data in variables

Avoid placing passwords, full credit card numbers, government ID numbers, or other highly sensitive information in dynamic variables. Variables appear in call transcripts and logs. Use masked fields or post-call analysis if you need to capture sensitive outcomes.

Variable added after publishing

If you add a new {{variable}} to the prompt and publish, any routes still pointing to the old published version will not have that variable defined. Check all routes after publishing a version that introduces new variables.

Assuming workflow variables match agent variables

Workflow lead variable keys and agent variable names must match. A mismatch means the workflow passes a value the agent does not recognize, and the agent falls back to the default. Audit the key names in both places when connecting a workflow to an agent.

Variables in Functions

You can use dynamic variables as parameter values in agent functions. For example, pass {{account_id}} to a customer lookup endpoint:

{
  "url": "https://api.example.com/customers/{{account_id}}",
  "method": "GET"
}

The variable is resolved at call time before the function is called. If the variable has no value, the fallback default is used. If neither is set, the literal placeholder text is sent to the API, which will likely cause the function to fail.

Verify Dynamic Variables

Test one call with complete values and one with a missing value. Confirm the welcome message, prompt, functions, transfer path, transcript, and fallback behavior use the expected value.

Recap

Use stable variable names, supply values from every launch path, add safe defaults, and test missing data. Never place secrets or information that should not appear in transcripts inside dynamic variables.

Batch Recipient Files

Map CSV columns to agent variables for batch campaigns.

Workflow Lead Variables

Connect workflow lead data to agent prompts.

Agent Settings

Set fallback defaults in Fallback Settings.

Prompting Guide

Write prompts that use variables effectively.

​Before You Begin

​Syntax

​Where Variables Can Be Used

​Built-In Default Variables

​How to Pass Variable Values

​Setting Fallback Defaults

​Testing Variable Rendering

​Variable Mistakes to Avoid

​Variables in Functions

​Verify Dynamic Variables

​Recap

​Related Reading

Batch Recipient Files

Workflow Lead Variables

Agent Settings

Prompting Guide

Before You Begin

Syntax

Where Variables Can Be Used

Built-In Default Variables

How to Pass Variable Values

Setting Fallback Defaults

Testing Variable Rendering

Variable Mistakes to Avoid

Variables in Functions

Verify Dynamic Variables

Recap

Related Reading