Variables and templating

Variables make your prompts dynamic: the same agent can greet a customer by name, confirm their phone number, or adapt to the channel, without duplicating the prompt. All variables and actions available to an agent are listed in the Variables & actions panel of the prompt editor.

Insert a variable or an action

Open the panel

In the Prompt tab, click Add variables in the toolbar of the welcome message or the agent prompt.

Find the item

Search for a variable or an action by name, or filter the list with Variables or Actions.

Insert it

Click + to insert it at the cursor position.

Selecting a variable shows its syntax, an example value, and its source at the bottom of the panel (for example “Injected by Volubile” for a system variable). The Actions filter lists the live-call actions configured on the agent. Inserting an action in the prompt lets you tell the agent exactly when in the conversation to trigger it.

Variables & actions panel open on the right of the prompt editor, listing system variables and showing the details of system.agentDid

Where variables come from

The call context is all the data available to the agent during the conversation. It feeds the prompt, and it is also sent to workflow actions during the call and to the post-call webhook.

Source	When it is available
System variables	Always, injected by Volubile with the `system.` prefix
Input context	Provided through the API, a campaign file, or SIP headers
Pre-call action	Output of the action run before the call

System variables

These variables are injected automatically on every call.

Variable	Description	Example
`system.agentDid`	The agent’s phone number (DID), in E.164 format. Available on inbound calls only.	`+33199001234`
`system.agentId`	Unique identifier of the agent. Useful to tell agents apart in your analytics.	`b8d9637f-ba51-…`
`system.callId`	Unique identifier of the call. For tracking, logging, or cross-referencing.	`40387944-5065-…`
`system.conversationType`	Conversation channel: `call` (phone) or `chat` (web widget).	`call`
`system.customerId`	Identifier of the customer in Volubile.	`1e1a79ee-c6ec-…`
`system.date`	Current date.	`2025-05-13`
`system.dayOfWeek`	Day of the week, in the account locale.	`tuesday`
`system.now`	Current date and time, in the configured time zone.	`2025-05-13 10:36:37`
`system.phone`	Caller’s phone number in local format. Best for spoken use.	`06 12 34 56 78`
`system.phoneE164`	Caller’s phone number in E.164 format. Best for database lookups or API calls.	`+33612345678`
`system.threadId`	Identifier of the conversation thread.	—
`system.timeHHMM`	Current time in HHMM format, convenient for time comparisons.	`1036`
`system.year`	Current year.	`2025`

Full system object example

{
  "system": {
    "agentDid": "+33199001234",
    "agentId": "b8d9637f-ba51-4aa2-84a4-80692f7bbd17",
    "callId": "40387944-5065-483f-942c-68bae81e70ec",
    "conversationType": "call",
    "customerId": "1e1a79ee-c6ec-4b07-89f0-9a414daaa9de",
    "date": "2025-05-13",
    "dayOfWeek": "tuesday",
    "phone": "06 12 34 56 78",
    "phoneE164": "+33612345678",
    "now": "2025-05-13 10:36:37",
    "timeHHMM": "1036",
    "year": "2025"
  }
}

Input context

The input context is the data you pass to the agent for a given call. Each key becomes a variable you can use in the prompt, for example {{ client_id }}. The input context is also passed to the pre-call action, which can use it to query your systems.

API
Campaign (Excel / CSV)
SIP headers

When you create an outbound call through the API, pass a context object in the request. It is injected when the call starts.

Initiate outbound calls

View the API reference

For an outbound campaign, each column of the file becomes a variable, set to the value in the row of the contact being called.

Column names must not contain spaces or special characters. Separate words with underscores (_), for example appointment_date.

For an inbound call over a SIP connection, Volubile adds the User-to-User header and every custom header starting with X-Volubile- to the context.Each header is converted into a variable:

the X-Volubile- prefix is removed;
the key is lowercased;
hyphens (-) are replaced with underscores (_).

User-to-User: 6796
X-Volubile-code: ABC123
X-Volubile-client-id: CL-45678
X-Volubile-client-segment: premium

{
  "user_to_user": "6796",
  "code": "ABC123",
  "client_id": "CL-45678",
  "client_segment": "premium"
}

Test with an input context

To check how your prompt renders without placing a real call, simulate an input context: click the pencil icon at the bottom of the Variables & actions panel. In the Input context window, enter a JSON object with the values you would send through the API, Excel, or SIP, then click Save. These values are used when you test the agent with the Test button.

{
  "first_name": "Camille",
  "client_id": "CL-45678",
  "appointment_date": "2025-06-02"
}

Input context window with an empty JSON editor and Cancel and Save buttons

Pre-call action

Before each inbound or outbound call, a pre-call action can enrich the context. It has access to the system variables and the input context, and its output is injected into the call context so you can use it in the prompt.

Use system.phoneE164 or an identifier passed in the input context (for example client_id) to look up the customer in your CRM before they even speak.

Write a dynamic prompt with Jinja

Volubile prompts use Jinja syntax, which combines static text with three kinds of delimiters:

Delimiter	Purpose	Example
`{{ ... }}`	Insert a variable	`Hello {{ first_name }}`
`{% ... %}`	Add logic	`{% if system.timeHHMM > "1800" %}Good evening{% endif %}`
`{# ... #}`	Comment (not sent to the model)	`{# Internal note #}`

Access data

{{ first_name }}                    {# Simple value #}
{{ client.address.city }}           {# Nested property #}
{{ client['address']['city'] }}     {# Equivalent syntax #}
{{ products[0].name }}              {# List item #}

Handle missing variables

A variable can be missing depending on where the call comes from. Check that it exists before using it:

{% if system.phone is defined %}
Can you confirm your number is {{ system.phone }}?
{% else %}
Could you give me your phone number?
{% endif %}

Adapt the prompt to the channel

The same agent can run on voice and chat. Use system.conversationType to adapt its instructions:

{% if system.conversationType == "chat" %}
Keep your answers concise and easy to read on screen.
{% else %}
Keep your answers natural to hear, suited to a spoken conversation.
{% endif %}

Nested conditions let you handle complex scenarios, but keep the structure readable so the prompt stays easy to maintain.

Jinja documentation

Full Jinja syntax reference

Product discovery

Telephony

Variables and templating

Insert a variable or an action

Where variables come from

System variables

Input context

Initiate outbound calls

Test with an input context

Pre-call action

Write a dynamic prompt with Jinja

Access data

Handle missing variables

Adapt the prompt to the channel

Jinja documentation

​Insert a variable or an action

​Where variables come from

​System variables

​Input context

Initiate outbound calls

​Test with an input context

​Pre-call action

​Write a dynamic prompt with Jinja

​Access data

​Handle missing variables

​Adapt the prompt to the channel

Jinja documentation

Insert a variable or an action

Where variables come from

System variables

Input context

Test with an input context

Pre-call action

Write a dynamic prompt with Jinja

Access data

Handle missing variables

Adapt the prompt to the channel