Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.
VariableDescription
agent_idUnique ID of the agent
execution_idUnique ID of the conversation or call
call_sidUnique ID of the phone call (Twilio, Plivo, etc.)
from_numberPhone number that initiated the call
to_numberPhone number that received the call
current_dateCurrent date in the caller’s timezone
current_timeCurrent time in the caller’s timezone
timezoneTimezone 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.
Agent Prompt editor with curly brace dropdown open showing User Variables section with referrer_name, referee_name, city, user_number and System Variables section with agent_id, call_sid
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

​
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.
1

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}.
2

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"
  }
}'
3

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.

​
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