Templates Guide

Templates are the message layouts Orqestra uses when an event fires. This page explains how to create them, write dynamic content, and use the global template system.

---

How templates work

1. You create a template and link it to an event type (e.g. order.confirmed) and a channel (Email, SMS, or Push).
2. You set the template to Active.
3. When your application fires an event with that event type, Orqestra finds the template, substitutes variables from your payload using Handlebars, and dispatches the rendered content.

One event type can have multiple templates — one per channel. All active templates for a matching event type fire simultaneously.

---

Creating a template

1. Go to Admin UI → Templates.
2. Click New Template.
3. Set the event type — this must exactly match the eventType you'll send in your API calls.
4. Select the channel (Email, SMS, or Push).
5. Write the content body (see format per channel below).
6. For Email, set a subject line (supports Handlebars variables).
7. Click Save, then toggle it to Active.

---

Handlebars variables

Every key in your variables object is available as {{fieldName}} in your template content and subject lines. The routing fields in payload (userId, recipientEmail, recipientPhone) are also available as a fallback, but template-specific data should live in variables.

Event request:

{
  "eventType": "order.confirmed",
  "payload": {
    "userId": "user_123",
    "recipientEmail": "alice@example.com"
  },
  "variables": {
    "orderNumber": "ORD-2026-1234",
    "customerName": "Alice",
    "total": "$89.00"
  }
}

Template content (SMS):

Hi {{customerName}}, your order {{orderNumber}} is confirmed. Total: {{total}}.

Rendered output:

Hi Alice, your order ORD-2026-1234 is confirmed. Total: $89.00.

Handlebars also supports:

• Conditionals: {{#if isPremium}}VIP notice{{/if}}
• Loops: {{#each items}}{{name}}{{/each}}
• Nested access: {{order.lineItems.0.name}}

---

Email templates (MJML)

Email templates use MJML — a markup language that compiles to responsive HTML that works correctly in Gmail, Outlook, Apple Mail, and mobile clients.

Basic MJML email:

<mjml>
  <mj-body>
    <mj-section background-color="#f4f4f4">
      <mj-column>
        <mj-text font-size="22px" font-weight="bold" color="#1e293b">
          {{title}}
        </mj-text>
        <mj-text font-size="14px" color="#475569" line-height="1.6">
          {{message}}
        </mj-text>
        <mj-button background-color="#4f46e5" href="{{ctaUrl}}">
          {{ctaLabel}}
        </mj-button>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

Use the Playground in the Admin UI to preview rendered MJML output with sample data before activating a template.

---

SMS templates

SMS templates are plain text. Keep them under 160 characters to avoid multi-part SMS charges.

{{title}}: {{message}}. Reply STOP to unsubscribe.

For the recipientPhone field, use E.164 format: +254712345678.

---

Push templates

Push templates deliver real-time in-app notifications via WebSocket. Use plain text — the content is displayed in your frontend notification UI.

{{title}} — {{message}}

The rendered content is delivered as { title, body, category, eventType } in the WebSocket publication.

---

Global templates

Five built-in event types work without custom templates. These resolve against platform-wide templates available to all tenants:

eventType	Recommended channel
global.info	Push, Email
global.success	Push, Email
global.warning	Push, Email
global.alert	Push, SMS
global.error	Push, Email

Recommended shape for global events:

{
  "eventType": "global.success",
  "payload": {
    "userId": "uuid",
    "recipientEmail": "user@example.com"
  },
  "variables": {
    "title": "Application Approved",
    "message": "Your loan application has been approved."
  }
}

Always include title and message in variables — these are the minimum fields expected by the built-in global templates.

---

Template Library

The Admin UI includes a Template Library — a collection of pre-built templates you can browse and clone into your workspace. This is the fastest way to get started without writing template content from scratch.

Go to Admin UI → Template Library to browse available templates.

---

Version history

Every save creates a new version. Previous versions are preserved so you can:

• Audit what content was sent for a specific notification log entry
• Roll back to a previous version if needed

Template versions are immutable — you can't edit a previous version, only the current active one.