# Templating (Scriban) (Reference: https://docs.iqra.bot/build/script/templating)

Iqra AI uses the **[Scriban](https://github.com/scriban/scriban)** engine to make your agents dynamic. This allows you to inject variables, format dates, perform math, and execute logic directly within your text fields.

You can use templating anywhere you see the **Braces Icon** <Braces className="w-4 h-4 inline-block" /> in the input label (e.g., AI Response text, SMS content, Tool configurations).

The Smart Editor [#the-smart-editor]

We have integrated a **Monaco-based Editor** for all template fields.

* **Intellisense:** As you type `{{`, a dropdown menu will appear listing all available variables in the current context.
* **Validation:** The editor provides real-time syntax highlighting to catch errors (like unclosed braces) before you save.

<Callout type="info" title="Validation">
  While the frontend editor catches syntax errors, the final execution and validation happen on the backend during the call.
</Callout>

***

Basic Syntax [#basic-syntax]

To inject a variable, wrap it in double curly braces:

```liquid
Hello {{ variables.user_name }}, how can I help you?
```

If `variables.user_name` is "Ahmed", the agent will say: *"Hello Ahmed, how can I help you?"*

Accessing Data [#accessing-data]

Data is organized into **Namespaces**. Here are the common sources available during a conversation:

| Namespace     | Variable              | Description                                                                         |
| :------------ | :-------------------- | :---------------------------------------------------------------------------------- |
| **Variables** | `{{ variables.key }}` | State stored via [Script Variables](/build/script/variables) or Set Variable nodes. |
| **Metadata**  | `{{ metadata.key }}`  | Data passed when launching the call (via API or CSV).                               |
| **Call**      | `{{ call.from }}`     | The caller's phone number.                                                          |
| **Call**      | `{{ call.to }}`       | The number dialed.                                                                  |
| **Agent**     | `{{ agent.name }}`    | The internal name of the agent.                                                     |

***

Formatting & Filters [#formatting--filters]

Raw data often sounds robotic. Use **Pipes** `|` to apply filters that format the output for natural speech.

Date & Time [#date--time]

*Raw ISO:* `2023-10-25T14:00:00` > *Spoken:* "Twenty twenty-three dash..." (Bad).

```liquid
// Format: Wednesday, October 25 at 2 PM
{{ variables.appt_date | date.to_string "%A, %B %d at %I:%M %p" }}
```

String Manipulation [#string-manipulation]

```liquid
// Capitalize the first letter
{{ variables.name | string.capitalize }}

// Safety: Default value if variable is empty
{{ variables.name | default "Valued Customer" }}
```

<Callout type="tip" title="Learn More">
  Scriban is powerful. Check the official documentation for a full list of built-in functions:

  * [Scriban Language Primer](https://github.com/scriban/scriban/blob/master/doc/language.md)
  * [Built-in Functions List](https://github.com/scriban/scriban/blob/master/doc/builtins.md)
</Callout>

***

Logic & Control Flow [#logic--control-flow]

You can add logic *inside* a text field. This is powerful for handling minor variations without creating complex branches in your graph.

Conditional Text (If/Else) [#conditional-text-ifelse]

Change the greeting based on a flag.

```liquid
{{ if metadata.is_vip }}
  Welcome back to the Premium line, {{ metadata.name }}.
{{ else }}
  Thanks for calling Customer Support.
{{ end }}
```

Loops (For) [#loops-for]

Iterate over lists returned by FlowApps (e.g., available calendar slots).

```liquid
I found the following times:
{{ for slot in variables.available_slots }}
  - {{ slot.time }}
{{ end }}
```

***

Best Practices [#best-practices]

1. Always use Defaults [#1-always-use-defaults]

If a variable might be null (e.g., a CSV column that is sometimes empty), accessing it directly might cause an error or silence.

**Bad:** `Hello {{ metadata.name }}`
**Good:** `Hello {{ metadata.name | default "there" }}`

2. Math Calculations [#2-math-calculations]

You can perform math directly in the template.

```liquid
// Calculate remaining balance
Your remaining credit is {{ metadata.limit - variables.current_spend }} dollars.
```