Install the widget

The RolChat widget is one floating button that adapts to the modules you have switched on: chat, a request-a-callback form, meeting booking, a lead form and knowledge base search all live inside it. Install it once; what it shows is decided in the dashboard.

1. Copy the snippet

In Settings → Widget, pick the site and copy the install snippet. It looks like this:

<!-- RolChat widget -->
<script>
  window.rolchatConfig = {
    "site_id": "ste_…",
    "account_id": "…",
    "widget_key": "wk1.<site>.<signature>",
    "modules": ["chat"]
  };
</script>
<script async src="https://widget.rolchat.com/stub.js"></script>

The widget key is public and safe to ship in a page. It names your site and is signed, so nobody can point a copy of the widget at your account. The dashboard adds further keys to the object (greeting, header title, theme, working hours, per-viewport layout) as you change the widget settings; copy the snippet again after changing them, or leave the object minimal and let the widget fetch the rest.

stub.js is a few kilobytes and loads the rest only when the visitor needs it: the chat surface on first open, tracking after consent, the consent banner where one is required.

2. Paste it before </body>

Add the snippet to every page where you want the widget, ideally through your site template or tag manager so it appears everywhere at once. The script loads asynchronously and does not block rendering; the first-load bundle is kept small on purpose so that it does not affect your Core Web Vitals.

3. Check it works

Open your site in a private window. The button appears in the corner you chose. In the dashboard, Visitors shows the new anonymous session in real time, and a message sent from the widget appears in the Inbox as a new conversation.

Identify logged-in users

If your visitors sign in to your product, tell RolChat who they are so conversations attach to the right contact:

window.rolchat.identify({
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Martin",
  phone: "+15551234567",
  external_id: "user_12345",
  custom_fields: { plan: "pro" },
});

Accepted traits are email, phone, first_name, last_name, external_id and a flat custom_fields object; anything else is ignored. RolChat looks the e-mail up in the CRM. If a contact exists, the session is linked to it and the agent sees the profile; if not, the details are kept and a lead is created when the visitor first writes.

For higher trust, your backend can sign the identity: pass the signature RolChat issues for the user alongside the traits, and the session is promoted only when the signature verifies. Call window.rolchat.reset() when the user signs out, otherwise the next person on that browser sees the previous conversation.

The JavaScript API

window.rolchat is available as soon as the stub runs; calls made before the bundle loads are queued and executed in order.

Method	What it does
show() / hide()	Show or hide the launcher
open() / close()	Open or close the chat panel
identify(traits)	Link the session to a person (above)
reset()	Forget the identity and start a fresh anonymous session
pushEvent(name, props)	Report a custom event for trigger messages and automation
trackPageView(path?)	Report a page view in single-page apps
setLocale(code)	Switch the widget language
showConsentPreferences()	Open the consent preference centre
on(event, handler) / off(event, handler)	Subscribe to chat:opened, chat:closed, message:sent, message:received, session:started

window.rolchat.pushEvent("cart_abandoned", { value: 129.9, currency: "EUR" });
window.rolchat.on("message:received", () => audio.play());

Language and direction

The widget speaks the language you pin with lang in window.rolchatConfig (for example "lang": "de"); without it, the visitor’s browser language, taken in the order of the browser’s preferences from the 40 languages RolChat supports; if none matches, English. The site’s own language setting is not used: to make the widget speak your site’s language, set lang. Arabic and Hebrew render right-to-left. Agent messages are not translated by the widget; the agent side can use AI live translation instead.

Cookies and consent

The widget does not track visitors before consent where a consent banner is required. If you use the RolChat Privacy module, the banner and the widget share one consent state. If you use another consent tool, the widget’s analytics events wait for the signal you configure in Settings → Privacy → Embed.

Where the widget is configured

What	Where
Colours, position, greeting, entry points, install snippet	Settings → Widget
Which modules appear inside the widget	Settings → Modules (per site)
Working hours and the offline message	Settings → Sites → Working hours
Trigger messages shown on specific pages	Marketing → Triggers