> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jinja syntax for prompts and messages

> Write conditions, loops and filters that work on calls: every value is a string, missing variables render empty, and a broken template drops its tags.

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

| You write | What it does |
| - | - |
| `{{ customer_name }}` | Inserts a value. Spaces inside the braces are optional. |
| `{% if ... %} ... {% elif ... %} ... {% else %} ... {% endif %}` | Includes text only when a condition holds |
| `{% for o in orders %} ... {% endfor %}` | Repeats text for each item in a list |
| `{{ value \| filter }}` | Changes a value: `{{ customer_name \| title }}` |
| `{% set name = ... %}` | Sets a name for the rest of the template |
| `{# ... #}` | A comment. Never reaches the caller or the model. |

### Conditions

```jinja theme={null}
{% if direction == "Inbound" %}
Thank the caller for calling.
{% elif direction == "Outbound" %}
Say you're calling from Hamsa Clinic about their appointment.
{% endif %}
```

```jinja theme={null}
{% if current_weekday in ["Friday", "Saturday"] %}Tell the caller we're closed today.{% endif %}
```

### Loops

With `orders` set to `[{"id": "A-1042", "status": "shipped"}, {"id": "A-1043", "status": "processing"}]`:

```jinja theme={null}
The caller has {{ orders | length }} orders:
{% for o in orders %}
- Order {{ o.id }} is {{ o.status }}.
{% endfor %}
```

Inside a loop, `loop.index` gives the position, starting at 1.

### Filters that come in handy

| Filter | Example | Result |
| - | - | - |
| `title`, `upper`, `lower`, `capitalize` | `{{ "sara ali" \| title }}` | `Sara Ali` |
| `int`, `float` | `{{ visits \| int * 2 }}` with `visits` = `"3"` | `6` |
| `round` | `{{ balance \| float \| round(1) }}` with `"1250.47"` | `1250.5` |
| `format` | `{{ "%.2f" \| format(balance \| float) }}` with `"1250.5"` | `1250.50` |
| `default` | `{{ plan \| default("standard", true) }}` with `plan` empty | `standard` |
| `length` | `{{ orders \| length }}` | `2` |
| `join` | `{{ items \| join(", ") }}` | `Tea, Cake` |
| `first`, `last` | `{{ items \| first }}` | `Tea` |
| `replace` | `{{ ref \| replace("-", " ") }}` | `A 1042` |

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.

| You want | Write | Not |
| - | - | - |
| Check a true or false value | `{% if is_vip == "True" %}` | `{% if is_vip %}` (the text `"False"` counts as true) |
| Compare a number | `{% if visits \| int > 2 %}` | `{% if visits > 2 %}` (an error: text can't be compared with a number) |
| Do arithmetic | `{{ visits \| int + 1 }}` | `{{ visits + 1 }}` |
| Compare a decimal | `{% if balance \| float >= 100 %}` | `{% if balance >= 100 %}` |

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:

| Template | Renders |
| - | - |
| `{{ missing }}` | nothing |
| `{{ missing.field }}` | nothing |
| `{{ missing \| int + 1 }}` | `1` (a missing value counts as 0) |
| `{% if missing %}yes{% else %}no{% endif %}` | `no` |

`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`):

```jinja theme={null}
{% if is_vip == "True" %}Welcome back{% else %}Hello{% endif %}, {{ customer_name | capitalise }}
```

The agent gets:

```text theme={null}
Welcome backHello, 
```

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 output](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/prompt-editor-preview-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=7c5dcf73171493e69b1ab2ca79f086a7)

### 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](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

## Call a project macro

In a flow step's text, you can call a Jinja macro from [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md#call-a-macro-from-a-flow-steps-text) that is used in prompts and switched on for the agent:

```jinja theme={null}
{{ greet(first_name) }}
```

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](https://docs.tryhamsa.com/agents/variables/system-variables.md).
* 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.

## Related

> [card] [Variables overview](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> Where values come from and which one wins.

> [card] [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md)
>
> Exact formats to compare against.

> [card] [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md)
>
> Prompt guidance for voice agents.

> [card] [Test values](https://docs.tryhamsa.com/agents/variables/test-values.md)
>
> Fix names the editor marks as not defined.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.