Variables — Finn docs

What a variable is

A variable is a placeholder in your prompt or workflow that gets replaced with real data when the call runs. You write {{contact.name}} in the prompt, and the agent says the actual name of the person it is calling.

Variables come from three places:

Source	Prefix	Set when
Audience row	`contact.`	Before the call, from the CSV or CRM record
Collected during the call	`state.`	When an Ask node saves an answer
Returned by an action	`state.`	When an Action node completes and returns data

Variables persist for the whole call. Once state.severity is set, every later node can read it.

Audience variables

Every column in your audience becomes available as a variable. The required columns are name, phone_number, and country_code. Any extra column you add becomes a custom field.

name, phone_number, country_code, account_tier, last_order_date, account_manager
Alice Chen, 5551234567, +1, Enterprise, 2026-03-12, Sam Patel
Bob Singh, 9876543210, +91, SMB, 2026-01-05, Maya Lee

Upload that and you can reference account_tier, last_order_date, and account_manager in the prompt for each call.

Two reference forms appear in the product: {{contact.name}} for the standard columns and {{account_tier}} for custom fields. Which prefix applies to custom fields is not yet settled in this documentation. Check the variable picker in the workflow editor before relying on a form you have not tested.

See Audiences for the full import and field-mapping reference.

Using variables in a prompt

Drop the variable inline. The agent reads the substituted text, not the braces.

Greet the caller by name. If {{account_tier}} is "Enterprise", mention that they have priority support and offer the direct line to {{account_manager}}.

You can also use variables in a condition rather than as spoken text. The model evaluates the substituted value, so a variable holding Enterprise behaves the same as if you had typed Enterprise into the prompt for that call.

Keep prompt logic on variables coarse. If you find yourself writing five nested conditions on the same field, that is a signal to build a workflow with Decision nodes instead. See Prompting.

Variables inside a workflow

An Ask node collects an answer and saves it under a variable name you choose.

Ask node
  Question:  "On a scale of one to ten, how severe are your symptoms?"
  Type:      number
  Save as:   severity

That value is then available as {{state.severity}} in every downstream node: Say node text, another Ask node's question, an Action node's parameters, or a Decision node's condition.

Action nodes write variables too. A Book Calendar action returns the booked time, so a later Say node can read it:

Got it, {{contact.name}}. I've booked you for {{state.appointment_time}}. We'll send a confirmation to {{contact.phone_number}}.

Variables and workflows are configured in the dashboard workflow editor (View All Finn → your Finn → Edit Workflow). There is no API for editing workflow nodes. You can export the whole workflow as JSON from the ⋯ menu if you want the variable names in version control.

What goes wrong

The caller hears the braces. If a transcript contains the literal string {{state.severity}}, the variable was never set under that name. The usual cause is a mismatch: the Ask node saved to severity_score and the Say node reads severity. Names must match exactly, including case. There is no fuzzy matching and no error at save time. You find out on a live call.

The value is empty. A custom field that is blank in the audience row substitutes as an empty string. The sentence still gets spoken, with a gap where the value should be. Write prompts that survive this: "mention their account manager if you know it" degrades better than "tell them Sam Patel is their account manager."

The literal string null gets read aloud. Leave empty CSV cells blank. The platform treats null and n/a as ordinary text, so the agent will say them.

The variable is not set yet. A Say node placed before the Ask node that populates it will substitute nothing. Order matters, and the editor does not check it for you.

The Ask node cannot parse the answer. Real callers do not answer in the format you expect. "Pretty bad, maybe an eight" may not parse as a number. Add a fallback edge to every Ask node so the flow re-asks or hands off instead of stalling, and consider switching the node to AI-evaluated so the model can interpret paraphrases.

Testing

Test on Chat opens a text simulator in the browser and shows each node's inputs and outputs, which is the fastest way to confirm a variable is populated. Test on Call is the end-to-end check. Do both before pointing a Finn at a real audience.