> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  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".
</Tip>

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

<AccordionGroup>
  <Accordion title="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.

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="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.

    ```csv theme={null}
    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](/batch-calls/recipient-files) for file format requirements.
  </Accordion>

  <Accordion title="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](/workflows/lead-variables-and-call-attributes) for how to define and map lead variables.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Setting Fallback Defaults

<Steps>
  <Step title="Open Agent Settings">
    In the agent builder, click the **Settings** tab, then navigate to **Fallback Settings**.
  </Step>

  <Step title="Find detected variables">
    The builder lists every `{{variable_name}}` it found in the prompt, welcome message, and voicemail message.
  </Step>

  <Step title="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 {{first_name}}". For amounts or dates, use a placeholder that prompts the caller to confirm: "your upcoming appointment".
  </Step>

  <Step title="Save and include in publish">
    Save the settings. Fallback values are included in the published version snapshot.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Variables in Functions

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

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Batch Recipient Files" icon="file-spreadsheet" href="/batch-calls/recipient-files">
    Map CSV columns to agent variables for batch campaigns.
  </Card>

  <Card title="Workflow Lead Variables" icon="database" href="/workflows/lead-variables-and-call-attributes">
    Connect workflow lead data to agent prompts.
  </Card>

  <Card title="Agent Settings" icon="settings" href="/agent-settings/overview">
    Set fallback defaults in Fallback Settings.
  </Card>

  <Card title="Prompting Guide" icon="pencil" href="/agents/prompts-and-welcome-messages">
    Write prompts that use variables effectively.
  </Card>
</CardGroup>