Skip to main content

Variables: where they come from and where they go

Module goal: learn to pass data into a call, pull out what the client said and compute derived values.
Call variables (dynamic variables) are the memory of the conversation. They have three sources:
  1. They come from outside — from a calling campaign (the columns of the contacts file), from a public API call or from the SIP headers of an inbound call. This is how the agent knows which doctor the client is booked with and at what time. A column reaches the agent under its own name from the file: contact_first_name, contact_last_name, contact_city and any columns of your own, such as doctor or visit_time. The contacts file template for the US market profile also has contact_zip and contact_state; the platform works out the contact’s time zone from the ZIP code.
  2. They are extracted from the conversation — by the Extract Variables node.
  3. They are computed — by the Code node or from a Function response.
Default values are set in the Agent variables window: it opens with the Manage or + Variable button on the tab of the same name, while the tab itself only shows the list. These values also serve as test data in the chat test. A declared variable with no value is substituted as an empty string; the call does not fail because of it. The In signature checkbox in the same window marks the variables that must arrive as a column of the contacts file: if the file has no such column, the campaign will not launch.
Agent variables panel with default values

Agent variables. The values here are defaults and test data; in live calls they are overridden by campaign or API data.

Agent variables panel with default values
Ten more variables exist in every call from the first word; you neither declare nor pass them. Three describe the call itself: {{direction}} (inbound, outbound or web), {{from_number}} and {{to_number}}. For an inbound call from_number is the caller’s number and to_number is the dialled number; for an outbound call it is the other way round. Numbers arrive as digits only, with the country code, without +, spaces or brackets: 77011234567 for Kazakhstan, 12125551234 for the US. If the agent reads a number aloud, bring it to a readable form with a Code node. Values from the public API and SIP headers are applied afterwards and override these variables, while a contacts file column with the same name never reaches the call. The chat test has no call: there the numbers come from the default values on the tab and stay empty without them; direction is web. The other seven are the date and time of the conversation: {{call_date}} (2026-09-24), {{call_date_us}} (09/24/2026), {{call_time}} (14:05), {{call_time_us}} (2:05 PM), {{call_weekday}} (the day of the week in English, Thursday), {{call_timezone}} and {{today}}. The form of {{today}} depends on the organization’s market profile: in Kazakhstan (kz) it is 2026-09-24, in the US (us_tcpa) it is 09/24/2026. The date is computed in the time zone of the contact or the organization and is recomputed on every call, in the chat test too, so a default value from the tab does not replace it. The full list and the order in which the time zone is chosen are in the reference, in Variables every call starts with.
Extract Variables node inspector: three variables to extract

Extract Variables is a silent node: with one structured call it pulls the preferred date, the part of the day and the reason for rescheduling out of what was said. When the answer must come from a fixed set — yes or no, for example — choose the enum type: such a value is easy to build a formula on.

Extract Variables node inspector: three variables to extract
The types of extracted variables are string, number, boolean and enum; with enum the model picks one of the listed values. Advice: write a variable’s description as an instruction to the model, not as a comment for a colleague. “Preferred visit date in YYYY-MM-DD format” works; “date” does not. Choose the format for where the value goes next: YYYY-MM-DD matches the form of {{call_date}}, MM/DD/YYYY that of {{call_date_us}}.
Code node inspector: Python code and output variables

Code is Python in a sandbox: build a string, normalize a phone number, compute a date difference. It reads vars and returns values through result; the variables to pick up are listed in Output variables. The sandbox has no network and no files — for those, use Function.

Code node inspector: Python code and output variables
Full-screen code editor of the Local time node: a now('Asia/Almaty') call and the result dictionary

Code with a clock, full screen: the hint at the bottom reminds you what the sandbox has — the vars dictionary, the result variable and now(…). The values from result are listed in Output variables and from then on live as call variables.

The sandbox has a clock: now("Asia/Almaty") or now("America/New_York") returns the time in the given IANA zone as a dictionary — date (YYYY-MM-DD), time (HH:MM), hour, minute, dow (1–7, Monday first), iso, epoch and the rest. The zone is required: now() without an argument or with an unknown zone is an error and leaves through the node’s error branch. import datetime does not work in the sandbox, so this is how you ask “what time is it” — no external time service is needed. And to simply name the date or time of the call you do not need Code at all: the ready-made {{call_date}} and {{call_time}}, or their US forms {{call_date_us}} and {{call_time_us}}, are enough.
The names vars, result and now belong to the sandbox itself — a result variable cannot be named like that, it would always stay empty. The validator warns about it rather than blocking publication.

Where {{variable}} is substituted

A placeholder expands in all authored text, not only in a node’s instruction: in the agent’s global prompt, in transition conditions (global ones included), in the goals summary, in function descriptions and arguments, in extraction fields, in the flex mode prompt and in the answering machine detection hint.
The global prompt expands placeholders. A script placed in the Global prompt reaches the model with the values substituted — you do not need to copy the text into node instructions to get the substitution.A name that does not exist in the call stays as text: the model will see {{name}}. An empty substitution would make a typo invisible — instead of an explicit signal, the agent would speak with a hole in the phrase.
Pitfall: a silent node is silent but takes timeExtract Variables is one more model call, and Code is code execution. In a voice call they sit between the client’s line and the agent’s reply, so they add directly to the pause before the answer. Do not put three silent nodes in a row where one is enough, and do not give them a “heavy” reasoning model — the inspector warns about it.