Embedding on a Website

Once the assistant is published and you have at least one device, there are several ways to put it on a site. They range from copy-paste simple to fully server-signed.

Tip

The Embedding tab in Dashboard → Deployment generates the exact snippet for each option below, using your project’s URLs and configured variables.

Simple iframe (most common)

Select a target device on the Embedding tab and copy the snippet:

<iframe
  src="https://<host>/chat/<orgSlug>/<projectSlug>/<deviceSlug>"
  width="100%" height="600px" frameborder="0"
  allow="microphone; camera; display-capture; autoplay"
></iframe>

The allow attributes let voice and avatar modes access the mic and camera.

Passing data in: External Variables

If your page needs to tell the assistant something (a visitor’s name, a product ID, a course code), declare External Variables on the Embedding tab. Each variable has a source:

Source	How it’s sent	Good for
URL Query	Appended to the iframe src (?user_name=VALUE)	Non-sensitive data
POST Body	Submitted via a small form that targets the iframe	Data you don’t want in a URL

The Embedding tab generates the matching snippet (iframe or form + iframe) for the variables you’ve declared.

Preselecting chat language with ?lang=

You can preselect the session language by adding a lang query parameter to the chat URL:

https://<host>/chat/<orgSlug>/<projectSlug>/<deviceSlug>?lang=nl

Ragtime applies this exactly like a user language pick in the UI.

When it applies

• If Chat Languages has an explicit selected list, ?lang= must match one of those selected language codes.
• If All Languages is enabled, any known Ragtime language code is accepted.
• Invalid or unknown codes are ignored (with an info-level browser console log).

Precedence with pre-experience

If pre-experience shows a manual language selector (for example, multiple explicitly selected languages), manual user choice takes precedence and ?lang= is ignored.

If pre-experience is enabled but no language selector is shown (single-language or no-manual-choice flow), ?lang= still applies.

Which links support this

?lang= works on all deployment routes that resolve into the chat runtime:

• /chat/<projectId> (internal preview)
• /chat/<orgSlug>/<projectSlug>/<deviceSlug> (published device links)
• /i/<token> (recipient links)
• /embed/... routes (the embed shell forwards query params to the inner chat URL)

HMAC-signed embeds (secure)

Enable Security → Require signature to prevent unauthorised use. When on, every request must carry a valid X-Ragtime-Signature header (HMAC-SHA256 of the body using your Signing Secret).

Trade-off: you can no longer use a static HTML snippet — the signed URL must be generated server-side on each load. The Embedding tab shows the signed-URL pattern and reminds you of this.

Restrict who may embed: Allowed Domains

Add the domains that are permitted to iframe the assistant (subdomains are included automatically). With the list empty, cross-origin embedding is blocked but same-origin/direct access still works. This is enforced via CORS and frame-ancestors.

Note

Allowed Domains restricts embedding, not the direct link. To restrict who can open the link directly, use the IP allow-list on the device.

Download packages

Deployment → Embedding → Download Packages gives you two ready-made bundles:

Starter Page

A standalone HTML file with the embedded chat plus a live event log — open it in any browser and watch the postMessage event stream. If HMAC signing or domain restrictions are enabled, you’ll need to host it behind a small backend.

SCORM package

A zipped SCORM 1.2 or 2004 package to upload directly into an LMS. The assistant runs inside the LMS player and reports completion via the SCORM API:

Ragtime event	SCORM status
Chat started	incomplete
Session ended naturally / by user	completed
Session ended by idle / max duration	completed
Session ended by error	incomplete
Window closed mid-session	Time committed, status unchanged

For modern LMS delivery with seat licensing, prefer LTI over SCORM.

Listening to the conversation from your page

The embed emits a postMessage event stream your page can react to: chat_started, thinking, response_start, response_given, emotion, action events, and — if you opt in under Additional Permissions → Transcript Events — transcript_user / transcript_assistant with the full conversation text.

Caution

Enabling Transcript Events means the full conversation text is forwarded to your embedding page. Ragtime does not store transcripts — you become responsible for informing your users that their conversation may be recorded.

You can also push data into a running chat with window.ragtime.send(type, detail), and — with Injection enabled — override instructions or pre-populate the chat at load time. Injection requires the assistant to use a Custom Persona (not a preset template). See the Chat Injection docs for details.