Variables

What a variable is

A variable is a placeholder in your welcome message or system prompt that is replaced with a contact's data when the call runs. Write {{ first_name }} and the Finn says the name of the person it is calling.

Variables come from the audience you deploy with. For each call, Finn looks up the contact's row in the audience by phone number, and each column of that row becomes a variable. Outbound deployments always have an audience, so this is mainly an outbound feature. See outbound-campaigns.

Where variables work

Set these in the dashboard: click Edit on the Finn's builder page, then the Call flow tab. You can also set the welcome message through the API as begin_message on api-finns.

Audience columns

Every column in your audience is available as a variable. Each contact has phone_number and country_code, usually name, and any other column you add is a custom field. See api-audiences.

name, phone_number, country_code, first_name, account_tier, account_manager
Alice Chen, 5551234567, +1, Alice, Enterprise, Sam Patel
Bob Singh, 9876543210, +91, Bob, SMB, Maya Lee

With that file you can reference {{ first_name }}, {{ account_tier }} and {{ account_manager }}.

Syntax

Wrap the column name in double braces. Spaces inside the braces are optional: {{first_name}} and {{ first_name }} are the same.

Names are matched to column headers ignoring case, spaces and punctuation, so {{ first_name }}, {{ First Name }} and {{ firstname }} all match a column headed First Name.

Using variables in a prompt

Drop the variable inline. The Finn reads the substituted value, not the braces.

You are calling {{ first_name }}, whose account tier is {{ account_tier }}. If the tier is Enterprise, mention priority support and offer to connect them with their account manager, {{ account_manager }}.

Keep logic on variables simple. If you need branching steps, use a call flow. See agents-tasks.

Checks before a deployment starts

When you deploy, Finn checks the welcome message and system prompt:

What goes wrong

A value is missing for some contacts. If a contact's cell is empty, that call gets a stand-in value, not real data. Fill every column you reference for every contact, or leave the variable out of the prompt.

Text values are read literally. A cell containing null or n/a is spoken as written. Leave cells you don't have data for empty.

The name doesn't match a column. Check the spelling against the file's header row. Matching ignores case and punctuation, but not different words: {{ tier }} doesn't match account_tier.

Testing

Test calls from Test → Phone call aren't tied to an audience row, so every variable gets a stand-in value. To hear real values, deploy to a small audience of your own numbers, using rows that look like your real data, including rows with empty cells. See agents-testing.