Dynamic Variables in DialNexa Agents

Use dynamic variables in DialNexa agents to personalize prompts, welcome messages, and function calls per caller. Covers syntax, built-in variables, how to pass values, fallback defaults, and test call usage.

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”.

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.

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": "[phone]",
  "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
[phone],Rahul,June 15,3200
[phone],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.

Test call modal

When placing a test call from the agent builder or Agents list, a modal appears before dialing. Enter variable values in the modal fields to test how the agent renders the prompt with specific data.

Test call modal values are not saved as defaults. They apply only to that specific test call.

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

1. Open Agent Settings

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

2. Find detected variables

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

3. 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”.

4. 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:

1. Open the agent builder and click the test call button.
2. In the test call modal, enter values for each variable.
3. Place the test call and listen to the welcome message and first prompt. Confirm the values appear correctly in speech.
4. 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.

Related Reading

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.