Skip to main content
Build Agents with VAW Native

Use Call Data and Variables in Your Prompt

Personalise each VAW Native call with {{variable}} placeholders: where values come from, the full list of system values, and the 4 KB limit.

Written By voiceaiwrapper

Last updated 26 days ago

Call data lets one agent sound personal on every call. Put a placeholder such as {{first_name}} in the prompt or greeting, and the agent uses the real value when the call starts: "Hi Maria, I'm calling about your appointment on Thursday."

This article explains how placeholders work, where their values come from, and every value VoiceAIWrapper provides for you.

Applies to: VAW Native agents.

How placeholders work

Type a name between double curly braces anywhere in Prompt Instructions or the greeting:

Hi {{first_name}}, this is Ava from Bright Smile Dental.
You're calling to confirm the appointment on {{appointment_time}}.
Today is {{system.current_date}}.
  • Names can use letters, numbers, underscores (_), hyphens (-) and dots (.). Spaces inside the braces are ignored.
  • Values are filled in once, when the call starts.
  • If a value is missing, it's left blank. "Hi {{first_name}}" becomes "Hi ," when there's no first name. Write your prompt so it still makes sense without the value, for example: "If you don't know the customer's name, don't use one."

Placeholders also work in some tool settings, such as the text of Send SMS and the request of a custom HTTP tool. Those are covered in the tool articles.

See which values your agent needs

As soon as the prompt, greeting or an attached tool uses a placeholder, the panel Data you are passing on to the agent appears under Prompt Instructions. It groups every value by where it comes from:

GroupWhere the value comes fromDo you need to supply it?
Passed inYou or your system, when the call startsYes, for outbound calls and tests
Provided by the systemVoiceAIWrapper, on every call. These names start with system.No
Saved by a toolA tool attached to the agent saves it from its response during the callNo, the tool fills it in

Hover over a value to see where it's used, such as Instructions or greeting, or which tool saves it. If tools need passed-in values that the prompt doesn't mention, the panel counts them, for example "2 values your tools need at the start of a call".

The Agent Settings tab, cropped to the bottom of Prompt Instructions and the panel under it, for an agent whose prompt uses {{first_name}}, {{appointment_time}} and {{system.current_date}} and which has a tool that saves a value. The Data you are passing on to the agent panel shows all three groups (Passed in, Provided by the system, Saved by a tool) as chips, with the mouse over one Passed in chip so its tooltip (Used in Instructions or greeting) is visible, and the help line Passed-in values must be supplied for outbound and test calls; inbound calls begin with values provided by VAW.

Values provided by the system

VoiceAIWrapper fills these in on every call. Copy the names exactly, including system.. Date and time values use the agent's timezone, set next to Add the current date and time to the prompt on the Agent Settings tab.

PlaceholderWhat it containsExample
{{system.current_datetime}}Date and time the call startedMonday, 3:15 PM 6 October 2026
{{system.current_date}}Date the call startedMonday, 6 October 2026
{{system.current_time}}Time the call started3:15 PM
{{system.current_day}}Day of the weekMonday
{{system.current_date_iso}}Start date as YYYY-MM-DD2026-10-06
{{system.current_time_utc}}Start time in UTC (ISO 8601)2026-10-06T19:15:00Z
{{system.timezone}}The agent's timezoneAmerica/New_York
{{system.call_direction}}web, inbound, outbound or chatinbound
{{system.agent_name}}The agent's nameFront desk agent
{{system.customer_number}}The customer's number: the caller on inbound calls, the number dialled on outbound calls+15125550123
{{system.agent_number}}Your number on this call. Empty on web calls+15125550100
{{system.call_id}}The call's ID, for matching the call in another system(a long ID)
{{system.customer_name}}The customer's name, when the call started with oneCurrently always empty
{{system.channel}}voice on a call, chat in a text chatvoice
{{system.source}}test, widget or preview for web calls and chats. Empty on phone callswidget

{{system.customer_name}} isn't filled in yet. To greet people by name, pass the name in yourself. Campaign leads already pass in {{first_name}} and {{last_name}}.

You can't pass in your own value with a name that starts with system.. A test call, chat or one-off call that tries is refused with "… is reserved for VAW system call data", and campaign lead fields with such names are ignored.

Where passed-in values come from

System values are always there. Passed-in values have to come from somewhere, and it depends on how the call starts:

How the call startsWhere passed-in values come from
Test call or chatYou type them under Call data for this test in the test sheet. They're optional; empty ones are left blank.
Call a number (one-off outbound call)You type them under Call data for this call before you click Call now.
Outbound phone campaignEach lead's first_name, last_name, phone_number and email, plus the lead's custom fields under their own names. A pre-call webhook can add more.
Inbound phone campaignThe caller's lead details, as above, plus anything the campaign's pre-call webhook returns.
Inbound call to a number (no campaign)Only what the number's Inbound webhook returns. With no webhook, the call has system values only. See Route Inbound Calls with the Phone Number Webhook.
Web widgetThe Page variables you allow the web page to send. See Visitor Limits and Page Variables.

Name your placeholders after your lead fields. If your leads have a custom field called appointment_time, use {{appointment_time}} in the prompt and every campaign call fills it in.

Limits

  • 4 KB of passed-in values per call. All passed-in names and values together must fit in 4 KB. Test calls, chats and one-off calls over the limit are refused with "Variables are too large (max 4 KB)". Campaign and webhook calls aren't refused: values that don't fit are dropped, so some placeholders end up blank. Keep values short: pass an ID or a date, not a whole document.
  • All values are text. Numbers, dates and true/false values arrive as text.
  • System values don't count toward the 4 KB.

Troubleshooting

The value wasn't supplied for that call. Check the call's Variables tab in Call Logs to see what the call actually received. Then fill it in under Call data for this test, add it to your leads, or return it from your webhook.

Check the spelling against the table above. A misspelled name that starts with system. is still treated as a system value, so nobody is asked to fill it in, and it stays blank. {{system.agent_number}} is also empty on web calls, and {{system.customer_name}} is always empty for now.

System date and time values use the agent's timezone. Open Agent Settings, click the timezone button under Prompt Instructions, choose the business's timezone, click Set, then Save changes.

Make sure it uses double curly braces with no extra characters, like {{first_name}}, and that you've typed it in the prompt or greeting. The panel updates as you type.