Home › How-To › Widget Embedding

Widget Embedding

Embed the OpenRails chat widget on your website with JWT authentication and customization

Overview

The OpenRails chat widget is an embeddable component that allows your users to interact with a bot directly from your website. It uses JWT-based authentication for secure access and supports visual customization to match your branding.

Setting Up the Widget

Create a Bot for the Widget

Create a dedicated bot in your project with the model, system prompt, and data lakes configured for your external users. See Starting a Conversation for bot creation.

Enable Widget Mode

In the bot settings, navigate to the Widget tab and toggle Enable Widget Embedding to ON.

Configure JWT Authentication

Set up JWT authentication to control widget access:

  • JWT Secret — Enter a shared secret key for signing JWTs
  • Token Expiration — Set the token lifetime (e.g., 24 hours)
  • Issuer — Specify the issuer claim for token validation

Whitelist Domains

Add the domains where the widget will be embedded to the Allowed Origins list. This prevents unauthorized embedding on other sites.

Copy the Embed Code

Click Copy Embed Code to get the HTML snippet for your website.

Adding the Widget

Embedding the widget is simple — add a single script tag to your website pointing to your OpenRails instance. All configuration (bot settings, knowledge base, branding, authentication) is managed server-side in the OpenRails dashboard.

No secrets in your code: Unlike many widget platforms, OpenRails handles authentication and configuration entirely server-side. No tokens, API keys, or sensitive settings are ever exposed in your page source.

Widget Customization

All customization is managed through the OpenRails dashboard under your bot's Chat Template settings:

Setting Description
Theme Light or dark color scheme for the widget
Position Where the widget appears on the page
Title Custom heading displayed in the widget header
Welcome Message Initial greeting shown when the widget opens
Brand Colors Primary accent color to match your site's branding
Domain Whitelist Approved domains where the widget is allowed to load
Tip: Changes to widget settings take effect immediately — no need to update the embed code or redeploy your site.
Important: Always configure domain whitelisting to prevent unauthorized use of your widget. Without it, anyone could embed your bot on their site and consume your LLM API credits.

Next Steps