Use Dynamic Variables to Personalize Voice AI Calls

Variables let you inject dynamic data into your agent’s prompts at call time. Personalize greetings, reference customer details, and pass metadata without changing the prompt itself.

Variable Types

System Variables

Predefined by Bolna. Automatically available in every call without any setup.

User Variables

Defined by you in the prompt with {{variable_name}}. Values are passed via the API or from CSV rows during batch calling.

System Variables

These are injected automatically into every conversation. No setup required.

Variable	Description
`agent_id`	Unique ID of the agent
`execution_id`	Unique ID of the conversation or call
`call_sid`	Unique ID of the phone call (Twilio, Plivo, etc.)
`from_number`	Phone number that initiated the call
`to_number`	Phone number that received the call
`current_date`	Current date in the caller’s timezone
`current_time`	Current time in the caller’s timezone
`timezone`	Timezone name per tz database

Inbound calls: from_number = caller, to_number = your agent Outbound calls: from_number = your agent, to_number = recipient

Current date and time are automatically appended to the system prompt. You can also reference them as variables directly in your prompt for more control over placement.

User Variables

Define your own variables by wrapping a name in {{}} in your prompt. Type { in the Agent Tab prompt editor to open the variable dropdown, which shows both existing user variables and system variables.

With {, you can:

Select an existing user or system variable
Define a new variable by typing a name that does not exist yet (e.g., {{appointment_date}})

You can also type @ in the prompt editor to insert existing variables, prompt modules, or custom functions. Unlike {, @ cannot create new variables. Any variable you define automatically appears as a test input field in the prompt variables for testing section.

Prompt variables for testing showing timezone selector and auto-detected fields for referrer_name, referee_name, city, and user_number — Prompt variables auto-detected from the prompt, shown as editable fields with a timezone selector

Brace Styles

{variable_name} is the canonical form. {{variable_name}} is also accepted, so a prompt carried over from a Jinja or Handlebars template works as written. The editor keeps whichever form you typed rather than rewriting it. Padding inside the braces — { variable_name } — is tolerated as well.

Reading Into a JSON Value

A variable can hold a whole JSON object or array, and the prompt can read into it with a path:

Their score is {prior.score}, and their first loan is for {prior[loans][0][amount]}.

Dot and bracket notation are interchangeable: prior.loans.0.amount and prior[loans][0][amount] address the same value. Quote a key that contains spaces, e.g. {order["line items"].total}. Only the root is a variable you fill in. {prior.score} and {prior.loans.0.amount} are two views of the same value, so they collapse onto a single prior entry — pass the whole object under that one key:

"user_data": {
  "prior": { "score": 720, "loans": [{ "amount": 15000 }] }
}

A path that lands on an object or array is substituted as JSON; anything else is substituted as its plain value.

In the dashboard, a variable read into with a path gets a JSON editor in the prompt variables for testing section instead of a one-line field.

Passing Variables via API

When making a single call, pass variable values in the user_data object. Every key in user_data maps to a {{variable_name}} in your prompt.

Define Variables in Your Prompt

Hi {{customer_name}}, this is Sam from {{company_name}}.

I see you contacted us on {{last_contacted_on}} about your order for {{product_name}}.
Your call reference is {call_sid}.

Pass Values in the API Call

curl --request POST \
  --url https://api.bolna.ai/call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": "123e4567-e89b-12d3-a456-426655440000",
  "recipient_phone_number": "+10123456789",
  "from_phone_number": "+1987654007",
  "user_data": {
    "customer_name": "Caroline",
    "company_name": "Acme Corp",
    "last_contacted_on": "4th August",
    "product_name": "Pearl shampoo bar"
  }
}'

Result After Substitution

Hi Caroline, this is Sam from Acme Corp.

I see you contacted us on 4th August about your order for Pearl shampoo bar.
Your call reference is PDFHNEWFHVUWEHC.

call_sid is a system variable and gets filled automatically.

Nested JSON Variables

Variable values aren’t limited to flat strings — a user_data value can be a whole JSON object or array, and double-brace {{ }} tokens reach inside it with dotted paths.

Syntax	What it renders
`{{customer}}`	The entire `customer` object, serialized as JSON
`{{customer.name}}`	One nested field
`{{orders.0.id}}`	Array elements by index (`{{orders[0][id]}}` also works)
`{customer_name}`	Flat substitution, unchanged from before

Pass a JSON object in user_data

{
  "user_data": {
    "customer": {
      "name": "Caroline",
      "tier": "gold"
    },
    "score_trend": {
      "q1": 712,
      "q2": 748,
      "history": [700, 712, 748]
    }
  }
}

Reference nested fields in your prompt

Hi {{customer.name}}, you're on our {{customer.tier}} plan.
Your latest score is {{score_trend.q2}}, up from {{score_trend.history.0}}.
Full trend data: {{score_trend}}

Result after substitution

Hi Caroline, you're on our gold plan.
Your latest score is 748, up from 700.
Full trend data: {"q1": 712, "q2": 748, "history": [700, 712, 748]}

Path rules:

The first path segment must be a top-level key of user_data. If you send "score_trend": {...}, then {{score_trend.q1}} resolves — but {{response_data.data.score_trend.q1}} does not, because there is no top-level response_data key. The path must mirror your JSON exactly, starting at the root.
Stringified JSON is parsed automatically — if your system sends "score_trend": "{\"q1\": 712}" (a JSON string instead of an object), paths still walk into it: {{score_trend.q1}} renders 712.
{{path}} renders objects and arrays as valid JSON; single-brace {path} keeps plain-string rendering for backward compatibility.
JSON literals in your prompt are safe. Braces that don’t look like a variable path (for example a JSON example you pasted into the prompt) are left untouched.

An unresolved {{path}} renders as {path} in the prompt (visible in transcripts as a literal brace token — a useful signal the data didn’t match), while an unresolved {path} renders as empty. If the agent speaks a literal {something}, check that the first path segment matches a top-level user_data key and that the nesting mirrors your JSON.

Nested variables work everywhere flat variables do: the agent prompt and welcome message, user_data on /call, userData in the Web Call SDK, and the JSON returned by incoming caller identification.

Setting the Timezone

Pass timezone in user_data to ensure accurate date and time values:

curl --request POST \
  --url https://api.bolna.ai/call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": "123e4567-e89b-12d3-a456-426655440000",
  "recipient_phone_number": "+10123456789",
  "user_data": {
    "timezone": "America/New_York"
  }
}'

Passing Variables via CSV (Batch Calling)

When using batch calling, upload a CSV file where each row is a call. The contact_number column is required. All other columns are treated as user variables and passed to the agent automatically.

contact_number,customer_name,company_name,product_name,last_contacted_on
+11231237890,Bruce Wayne,Wayne Enterprises,Batsuit,3rd March
+91012345678,Bruce Lee,Dragon Corp,Training Kit,15th June
+44999999007,James Bond,MI6,Gadget Pack,1st January

Each column name maps directly to a {{variable_name}} in your prompt. For the first row, {{customer_name}} becomes “Bruce Wayne”, {{product_name}} becomes “Batsuit”, and so on.

CSV columns are passed as-is without validation. Make sure column names match the variable names in your prompt exactly.

Next Steps

Agent Tab

Configure prompts and test variables in the editor

Prompting Guide

Variable syntax, prompt modules, and best practices

Batch Calling

Upload CSVs to make calls at scale with variables

API Reference

Full API docs for the Make Call endpoint

Quickstarts

Phone Numbers & Calling Setup

Outbound Calling

Inbound Calling

Native Telephony Integrations

Managing Live Calls

Prompting & Personalization

Tools & Function Calling

Post-Call & Analytics

No-Code & Automation

SIP Trunking Guide

Use Dynamic Variables to Personalize Voice AI Calls

Variable Types

System Variables

User Variables

System Variables

User Variables

Brace Styles

Reading Into a JSON Value

Passing Variables via API

Nested JSON Variables

Setting the Timezone

Passing Variables via CSV (Batch Calling)

Next Steps

Agent Tab

Prompting Guide

Batch Calling

API Reference

​Variable Types

System Variables

User Variables

​System Variables

​User Variables

​Brace Styles

​Reading Into a JSON Value

​Passing Variables via API

​Nested JSON Variables

​Setting the Timezone

​Passing Variables via CSV (Batch Calling)

​Next Steps

Agent Tab

Prompting Guide

Batch Calling

API Reference

Variable Types

System Variables

User Variables

Brace Styles

Reading Into a JSON Value

Passing Variables via API

Nested JSON Variables

Setting the Timezone

Passing Variables via CSV (Batch Calling)

Next Steps