Taalk Help Center

Script Variables and Formatting

Variables put each contact's details into what your AI agent says. Write a field name in curly braces, such as {name}, and the agent replaces it with the contact's value on every call.

Variables work in Objectives, Script and logic, Voicemail Script, In-Call Text Message and the transfer messages (Whisper to Agent, Fail Message to Contact).

Go to Outreach › AI Agents › Agents, open an agent, then click Edit on Configuration › Objectives and script. Use Snippets › Pronunciation formatter and Snippets › Call flow handling to insert the examples below.

Built-in variables

Variable What it holds
{name} The contact's name
{firstname} The contact's first name (used in the Gatekeeper opener snippet)
{agentName} The agent's spoken name from Identity › Agent Name. If that's blank, the name comes from the voice.
callDirection "IN" for inbound calls, "OUT" for outbound calls
_shift Empty during business hours. "afterhours" outside the campaign's working hours. Also set during the campaign's break.
media 'sms' or 'email' when the agent is replying by text or email. Empty on voice calls.

[Confirm] (C4) Exact casing of contact variables: {name}, {firstname}, {firstName}, {lastname}.

[Confirm] The value _shift takes during a break (anything non-empty counts as "not business hours" in the snippets).

Your own fields: the Taalk_ prefix

Any extra column you upload with your contacts is available if its name starts with Taalk_. For example, upload a column Taalk_State and write:

~I see you're in {Taalk_State}.
  • Use the exact column name you uploaded. {Taalk_State} and {Taalk_state} are different.
  • If a contact has no value, the variable is empty. Write lines that still make sense without it.
  • See Uploading contacts for getting fields into a campaign.

Formatters: {var%function}

Add % and a formatter name inside the braces to control how a value is spoken.

Formatter Example Input → output
lowercase {var%lowercase} Hello World → hello world
uppercase {var%uppercase} hello world → HELLO WORLD
capitalize {var%capitalize} alex → Alex
camel {var%camel} john smith → John smith
spelling (text) {code%spelling} ABC → A-B-C
spelling (number) {pin%spelling} 12345 → 1-2-3-4-5
expand_address {address%expand_address} 123 Main St. → 123 Main Street
us_state {Taalk_State%us_state} GA → Georgia
implied_hundreds {amount%implied_hundreds} 75 → 7500 (multiplies by 100 if under 100)
implied_thousands {amount%implied_thousands} 50 → 50000 (multiplies by 1,000 if under 1,000)
Date pattern {date%MM/DD/YYYY} A date → 01/05/2025

Common date patterns:

Pattern Output
MM/DD/YYYY 01/05/2025
MMMM Do YYYY January 5th 2025
dddd Monday
h:mm A 2:30 PM

Note that camel only capitalizes the first letter of the whole value ("John smith"), not each word.

Default values and random picks

~This is {agentName} with {Taalk_Company|"Acme"}.
~{RANDOM|Hi|Hello|Hey there} {name}.
  • {var|"default"} says the default when the field is empty.
  • {RANDOM|a|b|c} picks one option per call.

[Confirm] (C2) The {var|"default"} and {RANDOM|…} syntax and how the voice engine handles it.

Logic before the call: /*@if */

Blocks between /*@if … */, /*@else*/ and /*@endif*/ pick which part of the script the agent gets, based on variables.

Inbound vs outbound:

/*@if callDirection=="OUT"*/
~Hi {name}. This is {agentName} calling from Acme.
/*@else*/
~Thanks for calling Acme. How can I help?
/*@endif*/

After hours:

/*@if _shift == "afterhours"*/
~Our team is out right now. When is a good time to call you back?
/*@else*/
~Let me connect you with a specialist.
/*@endif*/

Business hours vs anything else: /*@if !_shift*/ … /*@else*/ … /*@endif*/.

Text or email replies: /*@if media === 'sms'*/ or /*@if media === 'email'*/.

For a short switch inside one line, use the inline style:

{callDirection!=="OUT"?"Thanks for calling us back.":"My name is {agentName}."}

Variables from plugins

Plugins can look up data during the call and return values the agent can use. See Plugins overview.

Troubleshooting

Problem Fix
The agent says the braces or the field name out loud The field name doesn't match the uploaded column. Check spelling and casing.
The agent reads a code as a word Use %spelling.
The agent says "G A" instead of the state Use %us_state.
A branch never runs Check the quotes and operator, for example callDirection=="OUT". Test both directions with Roleplay.