Skip to main content
Every text field that takes variables is a Jinja template. Besides {{name}}, you can branch with {% if %}, repeat with {% for %} and change values with filters such as | title or | int. This page shows the syntax that works on calls, the rules that catch people out (every value is a string), and what happens when a template has an error. The templates are Jinja2. Handlebars syntax such as {{#if}} is not supported.

The basics

Conditions

Loops

With orders set to [{"id": "A-1042", "status": "shipped"}, {"id": "A-1043", "status": "processing"}]:
Inside a loop, loop.index gives the position, starting at 1.

Filters that come in handy

Any standard Jinja2 filter works. The editor’s suggestions also offer JavaScript-style forms such as .length, .first, .trim() and .toFixed(). Don’t use them: on a call .length and .first render empty and .toFixed() is an error. Use the filters above.

Every value is a string

On a call, every variable reaches the template as text, whatever its data type: numbers, true and false, and values sent at call start. This changes how you compare. Booleans from the agent are written True and False, with a capital letter. A boolean you send at call start as JSON true also arrives as "True". Lists and objects are the exception that helps: a value that starts with [ or { and holds valid JSON is read back as a list or an object, so {{ orders[0].id }} and {% for o in orders %} work. If an object has a key named like a built-in method (items, keys, values, get), use brackets: {{ order["items"] | join(", ") }}. The dot form, order.items, is an error.

In tool parameters

When a tool parameter’s value is exactly one expression with a filter, the tool gets the filter’s type, not text. {{ visits | int }} sends the number 3; {{ is_vip == "True" }} without a filter sends text. Anything with text around the expression is sent as text.

When a variable has no value

A variable that isn’t set yet, or that doesn’t exist, doesn’t stop the call: default only replaces a variable that has no value at all. A variable set to empty text stays empty: {{ plan | default("standard") }} gives nothing when plan is "". Add true to replace empty text too: {{ plan | default("standard", true) }}.

What happens on a template error

If a template has an error (bad syntax, an unknown filter, comparing text with a number), the call goes on, and the agent uses the text with every Jinja tag removed. The text between the tags stays, from every branch. This template uses a filter that doesn’t exist (capitalise instead of capitalize):
The agent gets:
Both branches are kept and the name is gone. Raw template code never reaches the caller or the model, but the meaning can break, so test every template. Common causes:
  • Handlebars: {{#if is_vip}}VIP{{/if}} gives VIP on every call.
  • Comparing text with a number: {% if visits > 2 %} keeps both branches. Use visits | int.
  • A typo in a filter name.
  • A missing {% endif %} or {% endfor %}.

Write and preview in the editor

1

Open the editor

In a text field that takes variables, click Edit in expert mode. The Jinja2 template editor opens (“Edit your template with full Jinja2 syntax support”).
2

Write the template

Insert variables with Insert variable (Cmd+K on Mac, Ctrl+K on Windows). The editor marks syntax errors and names that aren’t defined.
3

Preview it

Open the Preview tab, adjust Test data (JSON) if you like, and click Preview. Regenerate test data fills in new sample values.
4

Save

Click Save template.
The Help tab has a Jinja2 quick reference. To find your way around a long template:
  • Find text: press Cmd+F on Mac or Ctrl+F on Windows. The search opens in the editor, not the browser’s page search. On the Variables tab, the same keys jump to its search box.
  • Jump to a macro: if the template defines a {% macro %}, hold Cmd (Ctrl on Windows) and click a call to it. The editor jumps to where the macro is defined.
  • Read a filter: hover a filter after |, such as title, to see what it does.
The Jinja2 template editor with an if/else and a for loop, the Preview tab showing test data and the rendered outputThe Jinja2 template editor with an if/else and a for loop, the Preview tab showing test data and the rendered output

The preview isn’t the call

“Sample data is used for variables. Actual data will be different at runtime.” The preview also differs from a call in these ways:
  • The preview’s sample data uses the variable’s type (a number, a true or false), but on a call every value is a string. A comparison like visits > 2 can work in the preview and fail on the call. Write templates for strings.
  • range() isn’t available in the preview but works on calls.
  • The agent adds its own instructions around your prompt on a call, which the preview doesn’t show.
To check a template for real, run a test call.

Call a project macro

In a flow step’s text, you can call a Jinja macro from Functions & macros that is used in prompts and switched on for the agent:
What the macro renders goes into the text where it is called. If it fails on a call, it renders empty and the rest of the text is unaffected.

Good to know

  • In a single prompt agent, the prompt is filled in when the call starts (and again if the voice or language changes during the call). A time variable in the prompt shows the time at that moment.
  • Write {% if direction == "Outbound" %} with a capital letter: system values such as Inbound, Outbound, Phone and Web are capitalised. See System variables.
  • The preview takes templates up to 100,000 characters. For a longer one, split it, or move long tables of data into a variable and loop over it.

Variables overview

Where values come from and which one wins.

System variables

Exact formats to compare against.

Write a prompt that works on calls

Prompt guidance for voice agents.

Test values

Fix names the editor marks as not defined.