Templating with Handlebars

Overview

UniversalChatbot uses Handlebars templating syntax to insert dynamic values into your flow messages, API requests, conditions, and other configurations. This allows you to personalize conversations and work with data collected during the flow.

With templating, you can:

• Address users by name in messages
• Include collected information in API requests
• Display dynamic data fetched from external services
• Reference system variables like timestamps and user IDs

Basic Syntax

Handlebars expressions are wrapped in double curly braces: {{expression}}

Simple Variable Substitution

To output the value of a variable, use its name within double curly braces:

Hello, {{name}}! Welcome to our service.

If name is set to "Sarah", this renders as: Hello, Sarah! Welcome to our service.

Nested Property Access

Access nested properties using dot notation:

Your order total is {{order.total}} with {{order.items.length}} items.

Accessing Data

Variables in your templates come from several sources:

Flow Variables

Variables created by nodes during flow execution. For example, a Prompt node that stores user input in a variable called user_email:

We'll send confirmation to {{user_email}}

API Response Data

Data returned from API Call nodes is stored in the variable you specify. Access the response body using dot notation:

{{api_response.body.user.name}}
{{api_response.body.account.balance}}
{{api_response.status_code}}

Arrays and Objects

When you reference an array or object directly, it's rendered as JSON:

Your tags: {{user.tags}}

Variable Sources

Variables available in your templates come from different sources:

System Variables

These variables are always available in every flow:

{{@today}}

Current date in YYYY-MM-DD format

{{@now}}

Current timestamp with time zone

{{@request.platform}}

Platform identifier (webchat, intercom, etc.)

{{@request.user.id}}

Unique identifier for the current user

{{@request.user.name}}

User's name (if collected or provided by platform)

{{@request.user.email}}

User's email address (if collected or provided by platform)

{{@request.user.phone}}

User's phone number (if collected or provided by platform)

{{@conversation_history}}

Full conversation so far as "User: …\nBot: …" plain text. Iterate individual messages with {{#each @conversation_history}}{{this.role}}: {{this.content}}{{/each}}. Use this in AI node prompts to provide conversation context.

{{@conversation.id}}

Internal conversation id. The @conversation.* namespace is sourced from the conversation record, so it stays available in triggers (e.g. conversation-closed) where the live @request.* context is not present.

{{@conversation.platform_conversation_id}}

The conversation's id on the underlying platform (e.g. the Intercom conversation id).

{{@conversation.platform}}

Channel the conversation lives on: http, intercom, telegram, or whatsapp.

{{@conversation.gateway}}

Integration used to reach that channel: http_simple, intercom_api, telegram_bot_api, or whatsapp_cloud_api. Useful as a trigger guard, e.g. {{@conversation.gateway}} == "intercom_api".

{{@conversation.history}}

Same transcript as {{@conversation_history}} (plain text, also supports {{#each}}), available under the conversation namespace for use in triggers.

{{@flow.*}}

The main conversation flow's collected variables: each node's output keyed by its variable, e.g. {{@flow.welcome_message.data.body}}. In the main flow these are also available unprefixed ({{welcome_message.data.body}}); inside a trigger, {{@flow.*}} is the only way to reach them, since the trigger runs with its own separate variables.

Platform-Specific Variables

When deployed to specific platforms, additional variables become available with user and context data from that platform. See the Deployments documentation for platform-specific variable references.

Supported Features

Block Helpers

Conditionals with #if

{{#if premium_member}}
Welcome back, valued member!
{{else}}
Consider upgrading to premium for more features.
{{/if}}

Negation with #unless

{{#unless email_verified}}
Please verify your email to continue.
{{/unless}}

Iteration with #each

Your items:
{{#each cart.items}}
- {{this.name}}: {{this.price}}
{{/each}}

Special variables available inside #each:

Example using @last to add commas between items:

{{#each items}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}

Context switching with #with

{{#with user.address}}
{{street}}, {{city}} {{zip}}
{{/with}}

Helper Functions

UniversalChatbot provides built-in helper functions for common operations. Use them directly or combine with #if for conditional logic.

String Helpers

Comparison Helpers

Use with #if for conditional rendering.

Logical Helpers

Array Helpers

Math Helpers

Number Formatting

A calculated number arrives as a decimal, so a budget worked out by multiply renders as 31500.0 on its own. That is fine inside a condition, but wrong in a sentence someone reads. These helpers write the number the way you would write it. Results from the math helpers above and values from a Table column both need this; a plain number straight out of an API response does not.

money gives two decimal places, number and round give whole numbers, and only number and money add separators. Pick the symbol yourself, since the helpers never add one: ${{money total}} or GHS {{money total}}.

Pass a number to choose the decimal places: {{round price 2}} gives 1234.57, and {{money budget 0}} gives 31,500. Every helper here takes one.

Reach for ceil whenever the answer is counted in whole things. Four items packed three to a box is 1.33 boxes, and round makes that one box with an item left over. ceil makes it two. floor is the other direction, for how many whole units fit.

Date & Time Helpers

Extract parts of a timestamp such as {{@now}} (or a date value from an API response). Both return a number, which you can compare with the comparison helpers or in a Condition node, which is useful for business-hours logic. The value is read in its own timezone; {{@now}} is UTC.

Other Helpers

Combining Helpers

Helpers can be nested using subexpressions (parentheses):

// Uppercase with fallback
Hello {{upcase (default name "guest")}}!

// Check if array has many items
{{#if (gt (size items) 5)}}
You have many items in your cart.
{{/if}}

// Combined conditions
{{#if (and (gt age 18) verified)}}
You're eligible for this offer.
{{/if}}

// Open during business hours (Mon-Fri, 8am-5pm UTC)
{{#if (and (and (gte (weekday @now) 1) (lte (weekday @now) 5)) (and (gte (hour @now) 8) (lt (hour @now) 17)))}}
Our team is online right now.
{{/if}}

What's Not Supported

No HTML Escaping

Unlike standard Handlebars, our implementation does not HTML-escape output since we're working with plain text messages, not HTML. This means {{variable}} and {{{variable}}} produce the same result.

Working with Arrays

Since array index access isn't supported, use these approaches instead:

Use #each to iterate

{{#each api_response.body.items}}
Item: {{this.name}} - {{this.price}}
{{/each}}

Structure APIs to return direct values

Instead of returning nested arrays requiring index access, configure your APIs to return the specific data you need:

// Configure API to return current_order directly
{{current_order.items}}

Access @index within #each

Within an #each block, you can access the current index using @index:

{{#each products}}
{{@index}}. {{this.name}} - ${{this.price}}
{{/each}}

Practical Examples

Personalized Greeting

Hi {{customer_name}}! Thanks for reaching out about your {{inquiry_type}}.

I can see you're contacting us on {{@today}}. Let me help you with that.

API Request URL

https://api.example.com/orders/{{order_id}}/status

Dynamic Request Body

{
  "customer_id": "{{customer_id}}",
  "email": "{{email_address}}",
  "requested_at": "{{@now}}",
  "platform": "{{@platform}}"
}

Conditional Message

{{#if order_status.body.shipped}}
Great news! Your order has shipped and should arrive by {{order_status.body.estimated_delivery}}.
{{else}}
Your order is being prepared and will ship soon.
{{/if}}

Listing Items

Here are the products matching your search:

{{#each search_results.body.products}}
{{@index}}. {{this.name}} - ${{this.price}}
{{/each}}