Variables

Variables are placeholders that Callers fills in for each conversation. Use them to greet contacts by name, reference their order or appointment, and pass data into actions and webhooks. A step like Hi {{firstName}}, I'm calling about your order {{orderNumber}} becomes a personal conversation for every contact.

Types of values

Kind	Where the value comes from	Where you can use it
Contact variables	Contact data: CSV columns, the API `data` object, triggers, or a pre-conversation action	Script steps, scenarios, instructions, actions, webhooks
Built-in values	Set automatically by Callers (`name`, `phoneNumber`, `currentDate`, …)	Same as contact variables
Metadata	IDs and phone numbers of the current call	Pre-conversation and in-call actions
Call Data	The finished conversation: status, transcript, summary, outcome	Post-call actions and webhooks
Transcript variables	Values the AI extracts from what the contact said	Actions (in-call and post-call)

Contact variables

Add a variable

In a step: type +, or click Variable under the text box, then type the name and press Enter. You can also select a word and turn it into a variable.
In the Variables panel: click the variables button in the editor header, type in Add variable, and press Enter.

Variables are written as {{variableName}}. The panel lists them under Variables in use (referenced somewhere in the agent) and Variables not in use.

A step being edited with a variable tag inserted at the end of the text and the variable picker open below it, listing name, phoneNumber, companyName, agentName, and productName with the hint Press Enter to create new variable — Inserting a variable in a step: the picker lists existing variables; press Enter to create a new one.

Variables panel with name, agentName, companyName, and productName under Variables in use, phoneNumber under Variables not in use, and an Add variable field — The Variables panel, grouped into Variables in use and Variables not in use.

To rename or delete a variable, click it in the panel and choose Edit or Delete. Callers updates every place it’s used: steps, scenarios, instructions, actions, pre-conversation actions, and triggers.

Naming rules

Letters, digits, _, and $ only. Start with a letter, _, or $. No spaces.
Up to 30 characters.
Names are case-sensitive: firstName and firstname are different variables.

Invalid names are fixed or removed automatically, with an “Invalid tag” message.

Required contact fields

A contact must have a value for every variable the agent uses. When you upload contacts, Callers checks:

the base fields: name and phoneNumber (Voice and Text agents) or name and email (Email agents), and
every variable used in the script, scenarios, instructions, and actions,

except variables that a pre-conversation action fills in. Those are optional on upload. Contacts with a missing or empty required value are skipped with Missing required fields: …. If your account uses versions, the check combines the variables of every published version.

Before uploading, open the Variables panel and check Variables in use. Each one needs a matching CSV column (or data key in the API). See Manage contacts for the API side. A stray variable you forgot to delete makes every contact fail validation.

Provide values

CSV
API
Pre-conversation action

Add a column for each variable, with the variable name as the header (for example, firstName, orderNumber). Map the columns during import. See Upload contacts.

Put values in the contact’s data object:

{
  "name": "Dana Levi",
  "phoneNumber": "+14155550123",
  "data": {
    "firstName": "Dana",
    "orderNumber": "A-10293"
  }
}

Same variable, three places

A variable is one name used in three places. For orderNumber:

1. CSV row
2. API data
3. Step text

The header is the variable name; each row supplies the value.

name,phoneNumber,orderNumber
Dana Levi,+14155550123,A-10293

Or the same key in the contact’s data object:

{ "name": "Dana Levi", "phoneNumber": "+14155550123", "data": { "orderNumber": "A-10293" } }

And the script reads it:

Hi {{name}}, I'm calling about order {{orderNumber}}. Is now a good time?

Dana hears: “Hi Dana Levi, I’m calling about order A-10293. Is now a good time?”

Precedence. Each contact has one value per variable. Re-uploading a contact (CSV or API) replaces its data, so the latest upload wins. A pre-conversation action that maps a response field to the same name overrides the uploaded value for that call, and stores it on the contact when Update contact data is on. Built-in values such as name and phoneNumber come from the contact itself.

Built-in values

Variable	Value
`name`	The contact’s name.
`phoneNumber`	The contact’s phone number.
`email`	The contact’s email. Required for Email agents; used for meeting invitations.
`timeZone`	The contact’s time zone (set on the contact or detected from the phone number).
`currentDate`	Today’s date, for example `Mon Oct 26 2026`, unless you supply your own value.

The agent also knows the current date and time in the contact’s time zone, so it can handle “tomorrow” or “next Tuesday” without a variable. The numbers of the current call (phoneTo, phoneFrom) aren’t variables; they’re metadata tags for use in actions.

Metadata

Metadata tags carry details of the current call. They’re available in pre-conversation and in-call actions (the Metadata tab in the tag picker).

Tag	Value
`callId`	The call’s ID
`contactId`	The contact’s ID
`campaignId`	The agent’s ID
`organizationId`	Your account ID
`phoneTo` / `contactPhoneNumber`	The contact’s number
`phoneFrom` / `agentPhoneNumber`	The agent’s number

These names are reserved and can’t be used as your own variables.

Call Data

Post-call actions and webhooks can insert Call Data tags: any field of the finished conversation, such as duration, status, transcript, recordingUrl, successCriteria.name, summary.<key question>, contact.data.<variable>, and extractedVariables.<name>. See Webhook payload for the full list.

Transcript variables

Transcript variables let the AI pull a value out of the conversation and pass it to an action, for example an order number the caller read out, or the date they chose. You define them on the action, under Variables Extracted with Prompt (called Transcript Variables on custom code actions).

Add the variable

In the action editor, click Add New Variable.

Describe it

Set the Variable Name, the Type, and a Description that tells the AI what to extract, for example “The 6-digit order number the customer provides”.

Use it in the request

Insert the variable into the URL, headers, query parameters, or body from the Transcript tab of the tag picker.

Type	Use for
Text	Free text: names, addresses, reasons
Number	Quantities, amounts, IDs that are purely numeric
Boolean	Yes/no answers
Array	Lists, such as several items in an order

Variables Extracted with Prompt section with one variable: Variable Name specialOccasion, Type Boolean, and the description Is this booking for a birthday, honeymoon, anniversary or another special occasion? — A transcript variable under Variables Extracted with Prompt: name, type, and the description the AI follows.

Names are converted to camelCase (or snake_case if you use _) and must start with a letter.

Arrays and the schema designer

For an Array, click Define schema to describe each element. In Define item schema, pick the Type of each item. For objects (the default), click Add field and set each field’s Field name, Type (Text, Number, Boolean, Array, or Object), Required, and a description that helps the AI fill it. Field names start with a lowercase letter and use letters, numbers, and _. Click Save schema. Example: an items array whose objects have sku (Text, required), quantity (Number, required), and notes (Text).

Post-call extraction

Post-call actions and advanced webhooks also have Variables Extracted with Prompt. These are extracted after the conversation ends and sent as extractedVariables in the payload.

Mix sources in one request

Each source has its own tag syntax, so an action can combine them in a single URL or body. The tag picker inserts the right syntax for you; this is what the template looks like underneath:

Tag type	Syntax	Example
Variable (contact data)	`{{name}}`	`{{orderNumber}}`
Transcript (AI-extracted)	`[[name]]`	`[[issueDescription]]`
Metadata (current call)	`<#name#>`	`<#callId#>`, `<#phoneTo#>`
Call Data (post-call only)	`<<path>>`	`<<successCriteria.name>>`

An in-call HTTP action that files a support ticket for the order the contact is calling about:

URL

https://api.example.com/orders/{{orderNumber}}/tickets?caller=<#phoneTo#>

Body

{
  "orderNumber": "{{orderNumber}}",
  "customerName": "{{name}}",
  "issue": "[[issueDescription]]",
  "callbackRequested": "[[wantsCallback]]",
  "source": { "callId": "<#callId#>", "agentId": "<#campaignId#>" }
}

Here orderNumber and name come from the contact, issueDescription and wantsCallback are Variables Extracted with Prompt the AI fills from the conversation, and callId, phoneTo, and campaignId are metadata. Values that look like JSON (objects, arrays, numbers, booleans) are inserted as JSON; everything else as a string.

Test with mock values

When you click Send Test Request on an action, a dialog asks for a value for each variable (“Enter mock values to send a request”). Type them, or click the AI button (Generate mock values) to fill realistic examples automatically. Values that look like JSON are sent as JSON. When you place a test call, the test form asks for each contact variable. See Test your agent.

FAQ

Why were some contacts skipped during import?

They were missing a value for a variable the agent uses. Check Variables in use in the Variables panel and compare with your CSV headers. Header names must match the variable names exactly.

Can a variable be optional?

Only if a pre-conversation action fills it in. Otherwise, every variable the agent references is required. If some contacts won’t have a value, don’t reference it as a variable; describe the fallback with an Instruction instead.

What happens if I rename a variable?

Every usage is updated. Contacts you already uploaded keep the old key in their data, so re-upload or update them with the new name.

Upload contacts

Map CSV columns to variables.

Actions

Use variables in API requests.

Webhook payload

Every Call Data field.

Script editor

Insert variables with inline tags.

Get started

Build your agent

Guardrails and security

Test and deploy

Voice

Channels

Contacts and outreach

Results and analytics

Human operators

Best practices

Account and administration

Enterprise

Resources

Types of values

Contact variables

Add a variable

Naming rules

Required contact fields

Provide values

Same variable, three places

Built-in values

Metadata

Call Data

Transcript variables

Arrays and the schema designer

Post-call extraction

Mix sources in one request

Test with mock values

FAQ

Upload contacts

Actions

Webhook payload

Script editor

Types of values

Contact variables

Add a variable

Naming rules

Required contact fields

Provide values

Same variable, three places

Built-in values

Metadata

Call Data

Transcript variables

Arrays and the schema designer

Post-call extraction

Mix sources in one request

Test with mock values

FAQ

Related

Upload contacts

Actions

Webhook payload

Script editor