Dynamic Variables

Dynamic variables let you personalize each conversation with runtime data. Use them to inject caller names, order IDs, account details, or any other information into your agent's system prompt, first messages, and tool configurations.

Syntax

Variables use double curly braces:

{{variable_name}}

For example:

Hello {{customer_name}}, how can I help you with order {{order_id}} today?

Where to Use Variables

Variables can be used in the following places:

Location	Example
System Prompt	`You are assisting {{customer_name}} who is a {{customer_tier}} customer.`
First Messages	`Hello {{customer_name}}, welcome to our support line.`
Tool URLs	`https://api.example.com/orders/{{order_id}}`
Tool Request Bodies	`{ "customer_id": "{{customer_id}}" }`

How Variables Are Defined

Variables are auto-detected from your system prompt. When you type {{variable_name}} in the system prompt, Voxagent automatically recognizes it and adds it to the agent's variable list.

You can also manually manage variables in the Variables section of the agent configuration.

Variable Properties

Each variable has the following properties:

Property	Description
Name	The variable name as used in `{{name}}` syntax.
Type	The data type: `string`, `number`, `boolean`, or `integer`.
Description	A human-readable explanation of what this variable represents.
Default Value	The value used if the variable is not provided at runtime.
Nullable	Whether the variable can be `null` (omitted).

Always set a sensible default value or mark variables as nullable. If a required variable is missing at runtime and has no default, the raw {{variable_name}} text may appear in the agent's speech.

Passing Variables at Runtime

There are three ways to supply variable values when starting a conversation:

1. API Dispatch

When starting a conversation via the API, include variables in the request body:

curl -X POST https://api.voxagent.app/api/v1/conversations/dispatch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "phoneNumber": "+1234567890",
    "variables": {
      "customer_name": "Alice",
      "order_id": "ORD-12345"
    }
  }'

When using the embedded widget, pass variables as URL query parameters:

https://your-site.com/support?customer_name=Alice&order_id=ORD-12345

The widget reads these parameters and passes them to the agent session.

3. Campaign Items

When running an outbound campaign, variables are mapped from Excel columns. Each row in the contact list provides variable values for that specific call.

Variable names are case-sensitive. {{customer_name}} and {{Customer_Name}} are treated as different variables.

Example: Personalized Support Agent

System Prompt:

# Personality
You are a friendly customer support agent for Acme Corp.

# Context
You are speaking with {{customer_name}}, a {{customer_tier}} tier customer.
Their account ID is {{account_id}}.

# Goal
Help the customer with their inquiry. If they ask about an order,
use the check_order tool with their account ID.

# Guardrails
- Never share information about other customers.
- If you cannot help, offer to transfer to a human agent.

First Message:

Hello {{customer_name}}, thank you for calling Acme Corp. How can I assist you today?

When a call comes in with customer_name=Alice, customer_tier=Gold, and account_id=AC-789, the agent will greet Alice by name and have full context about her account.