Variables

An agent’s prompt and greeting are templates: {{userdata.name}}, {{vars.brand_name}} and {{system_vars.date}} are substituted when the agent starts. This page covers the template roots, the agent’s own vars declarations, and the six system_vars Talqing fills in. Facts about the person live in userdata.

Template roots

Root	Holds	Prompt, greeting	Tool operation
`{{userdata.*}}`	Session state about the person; tools can write it	Yes	Yes
`{{vars.*}}`	Values the request that started the session supplied; read-only	Yes	Yes
`{{system_vars.*}}`	This call’s numbers and direction, plus the agent’s clock; read-only	Yes	Yes
`{{args.*}}`	Arguments the model sent to this tool call	Refused	Yes
`{{tooldata.*}}`	Values an earlier operation in the same tool run published	Refused	Yes
`{{secrets.NAME}}`	A workspace secret, or the session’s own	Refused	`http` and `code` only

{{recording.notice}} is legal in the greeting only — see recording. The tool side (tooldata, publish_fields, set_variable) is on templating and data. The same rules apply to a handoff destination’s description, summary_prompt and message, and to voicemail_detection.message.

Tokens that are refused at save

Anything shaped like {{…}} is checked, not only the known roots:

You wrote	Result
`{{name}}`, `{{customer.number}}`, `{{userdate.name}}`	Error: not a variable — it would be sent with the braces
`{{sipdata.human_phone_number}}`, `{{system.date}}`	Error naming the rename: write `{{system_vars.…}}`
`{{userdata}}`, `{{vars}}`	Error: that is the whole bag; add a dot and a field name
`{{system_vars.foo}}`	Error: lists the seven system variables
`{{vars.region}}` not in `config.vars`	Warning: empty unless the request supplies it

There is no escape syntax: prose containing {{anything}} cannot be saved. A code operation’s TypeScript source is exempt.

vars

config.vars declares the variables the agent reads as {{vars.name}}. Values arrive per session on POST /v1/calls/token, POST /v1/calls/outbound, POST /v1/calls/batches and POST /v1/chats, and override the declared default.

{
  "prompt": "You answer for {{vars.brand_name}}. Book through {{vars.api_domain}}.",
  "greeting": {"message": "Thanks for calling {{vars.brand_name}}. How can I help?"},
  "vars": [
    { "name": "brand_name", "description": "Reseller brand", "default": "Acme Dental" },
    { "name": "api_domain", "description": "Booking API base URL", "required": true }
  ]
}

vars is a list, so a PATCH replaces it whole — send every variable you mean to keep. Supplying values for one call:

curl -X POST https://api.talqing.com/v1/calls/token \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "6f2b0f4c-2f3d-4c7a-9c1e-1d2a8f0b41c7",
    "contact_key": "user-42",
    "vars": { "brand_name": "Northside Dental", "api_domain": "https://booking.northside.example" }
  }'

const call = await talqing.calls.token({
  tokenRequest: {
    agent_id: "6f2b0f4c-2f3d-4c7a-9c1e-1d2a8f0b41c7",
    contact_key: "user-42",
    vars: { brand_name: "Northside Dental", api_domain: "https://booking.northside.example" },
  },
});

call = talqing.calls.token(
    agent_id="6f2b0f4c-2f3d-4c7a-9c1e-1d2a8f0b41c7",
    contact_key="user-42",
    vars={"brand_name": "Northside Dental", "api_domain": "https://booking.northside.example"},
)

Rules

Values are strings. Any other JSON type is refused.
One bag per session. It reaches every agent the session runs — team members and handoff targets included. Each agent merges it over its own defaults. Nothing inside the session (tool, hook, model) can write vars.
The model sees the values. A per-session credential goes in secrets on the same request (session secrets), a shared one in a workspace secret; a tool reads either as {{secrets.NAME}}.
An empty string is a value. {"api_domain": ""} overrides the default.
required: true refuses the session when the variable has no default and no value was supplied, before anything is compiled: this session needs values it was not given / 'api_domain' is required and has no default. Nothing is enforced mid-session: a handoff target missing a value reads it as empty.
Inbound phone calls supply no values, so only defaults resolve. A voice agent requiring a variable with no default cannot be assigned to a phone number; assigning, publishing while assigned, and rolling back to such a version are all refused.
agent_override.vars changes the declarations for one call; top-level vars supplies values. See per-call configuration.

system_vars

Seven keys, filled in by Talqing; any other key is refused at save. GET /v1/catalog returns them as system_vars, each with the channels it has a value on (empty: every one).

Key	Example	Available
`human_phone_number`	`+919876543210`	Phone calls, WhatsApp calls and chats, media streams; the person (who called or wrote to you, or whom you called or wrote to)
`agent_phone_number`	`+912248900123`	The same; your number in this session
`direction`	`inbound` / `outbound`	The same (media streams only when the platform reports it); `inbound` when they started the call or chat
`channel`	`whatsapp_call`	Every session: `phone_call`, `whatsapp_call`, `whatsapp_message`, `web_call`, `chat`, `telegram` or `stream`
`now`	`2026-08-19T19:26:59+05:30`	Every channel, when `timezone` is set
`date`	`Wednesday, 19 August 2026`	Every channel, when `timezone` is set
`time`	`7:26 PM`	Every channel, when `timezone` is set

The three phone keys are absent on web calls, API chats and Telegram (they resolve to nothing). Using one on a video agent, which only takes web calls, is a warning. A WhatsApp user who hides their number has no human_phone_number.
channel lets one agent serve several channels and adapt: answer shorter on whatsapp_message, or skip spelling out a link on phone_call. It is absent on a standalone task run.
The clock keys need config.timezone, an IANA name such as Asia/Kolkata. Using one without it is a save error.
now is for APIs. Using it in the greeting or voicemail message is a warning — use time or date in spoken lines.
In a prompt or greeting the clock is frozen at the moment the agent started (call answer, handoff, or chat start/resume). In a tool operation it is the moment the operation ran. For time elapsed on every turn, set elapsed_time: true (cascade pipelines only).

userdata, vars, system_vars or secrets

	`userdata`	`vars`	`system_vars`	`secrets`
Describes	The person	This session	The call and the clock	Your credentials
Set by	The request, then tools mid-session	The request that starts the session	Talqing	A workspace admin, or the request that starts the session
In a prompt	Yes	Yes	Yes	No
Seen by the model	Yes	Yes	Yes	No
After the session	Merged onto the contact record	Discarded	Not stored	Workspace: kept. Session: deleted with the session’s content

If a value would be wrong to replay into the person’s next conversation, it is a var.

Userdata

Seeding, writing and keeping facts about the person.

Templating and data

args, tooldata, publish_fields, set_variable.

Get started

Build

Guides

Template roots

Tokens that are refused at save

vars

Rules

system_vars

userdata, vars, system_vars or secrets

Next

Userdata

Templating and data

​Template roots

​Tokens that are refused at save

​vars

​Rules

​system_vars

​userdata, vars, system_vars or secrets

​Next

Userdata

Templating and data

Template roots

Tokens that are refused at save

vars

Rules

system_vars

userdata, vars, system_vars or secrets

Next