Custom Templates

By default a device 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

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.
Two more tokens are available for per-device context:
- {{DEVICE_SLUG}} — the URL-safe device identifier (e.g. kiosk-a).
- {{DEVICE_NAME}} — the human-readable device label (e.g. “Lobby Kiosk”). Both are HTML-escaped and safe to use as text content or inside double-quoted attribute values.
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 device (the “Custom embed template” toggle on the device). The External Variables, transcript events and injection mechanics described in Embedding work the same way inside a custom template.