Custom Templates

By default a channel serves Ragtime’s standard chat UI. A custom template lets you wrap that chat in your own HTML page — your header, footer, styling, surrounding copy and scripts — so the experience looks like part of your site or product rather than an embedded widget.

How it works

1. You author an HTML page. Wherever you want the chat to appear, you drop the token {{RAGTIME_IFRAME}}; Ragtime replaces it with the chat iframe at serve time.
2. Two more tokens are available for per-channel context:
   • {{CHANNEL_SLUG}} — the URL-safe channel identifier (e.g. kiosk-a).
   • {{CHANNEL_NAME}} — the human-readable channel label (e.g. “Lobby Kiosk”). Both are HTML-escaped and safe to use as text content or inside double-quoted attribute values. The legacy {{DEVICE_SLUG}} / {{DEVICE_NAME}} tokens still work the same way for templates saved before this rename.
3. You can bundle media, CSS and JS assets alongside the template.

Where it is served

The custom template page is served directly on Ragtime’s own origin:

Route	Purpose
/embed/<orgSlug>/<projectSlug>/<deviceSlug>	Live (public, from the published snapshot)
/embed/<projectId>	Preview of the draft template (org members only)

Because it runs on Ragtime’s origin, the chat iframe inside it is same-origin — fonts, scripts and API calls “just work.” The page sets a permissive frame-ancestors header so an LMS or your own site can still iframe it.

Event bridge

Ragtime bridges the chat’s postMessage events so your template’s JavaScript can listen with:

window.addEventListener('ragtime:event', (e) => {
  console.log(e.detail); // { event: 'response_given', ... }
});

Every ragtime-* message is also re-forwarded up to window.parent, so if your template is itself framed by an external host, the host sees the same event stream it would see when framing /chat/... directly.

Turning it on

A custom template is enabled per channel (the “Custom embed template” toggle on the channel). The External Variables, transcript events and injection mechanics described in Embedding work the same way inside a custom template.

Note

The Allowed Domains allow-list on the Embedding tab applies to external embedding (hosting the chat on another origin). It does not apply when the experience is served through a Ragtime custom template, since that runs on Ragtime’s own origin.