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
_shifttakes 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. |