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)

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. Literal values must be quoted.

Logical Helpers

Array Helpers

Math Helpers

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}}

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}}