In Spotler Chat+ you add the new, component-based chat widget to a website by placing the script snippet that you generate under Settings Widget; from that same screen you also configure the widget's appearance and behavior, and optionally control the widget programmatically via a JavaScript SDK.
The current widget remains fully supported, but the new widget offers extra possibilities and better performance. You can apply the new script to your website by following the next instructions.
You install the widget by placing the script snippet from Chat+ on your website and publishing the change. Additional display settings and behavior are configured in the admin screen, and for custom integrations a JavaScript SDK is available with which you can programmatically open, close, or provide context to the widget.
On this page, the following topics are covered:
- How do you add the widget to your website?
- Which settings can you manage in the widget configuration?
- How do you control the widget programmatically with the JavaScript SDK?
- What do you need to change when migrating from the old widget?
How do you add the widget to your website?
You generate the embed code for the widget in Spotler Chat+ under Settings Widget. Follow these steps to install the widget:
- Open the Settings section in Spotler Chat+ and go to Widget.
2. Copy the generated script snippet, which contains the unique widget ID (GUID).
<script id="obi-bots-launcher" src="https://cloudstatic.obi4wan.com/chatplus/obi-launcher.bundle.js"></script>
<script>
const widgetController = OBI.bots("YOUR-WIDGET-ID");
</script>3. Place the script snippet in the code of the website on which the widget should appear.
4. Save the settings and click Publish to make the change active.
You can also initialize the widget with configuration overrides and context about the visitor, for example to pass along data such as customer number or name:
const widgetController = OBI.bots(
"JOUW-WIDGET-ID",
{ open_by_default: false },
{ customerId: "12345", name: "Jan Jansen", plan: "premium" }
);Changes only take effect after publishing
Settings in Chat+ only become visible on the website after you click Save and then Publish; this applies to every change to the widget settings, not only the initial installation.
Which settings can you manage in the widget configuration?
In the admin screen of Spotler Chat+, under Settings Widget, you customize the widget without code changes:
- Appearance and theme: primary colors, header colors, logo or avatar, fonts, dimensions, and position on desktop and mobile.
- Launcher and messages: showing or hiding the launcher text bubble, unread badges, and a custom launcher button.
- Behavior: automatically opening on load via Open by default, excluded pages via Blacklisted URLs or regular expressions, and the option for end users to have a conversation transcript sent to their email address via Transcript request.
How do you control the widget programmatically with the JavaScript SDK?
The OBI.bots() function returns a widget controller with which you can control the chat from your own website, for example via your own contact button:
| Method | Description |
|---|---|
widgetController.open() |
Opens the chat widget programmatically. |
widgetController.close() |
Closes the chat widget. |
widgetController.toggle() |
Toggles between opening and closing. |
widgetController.startSession() |
Immediately starts a new chat session. |
widgetController.refresh() |
Restarts the conversation and clears the current message view. |
widgetController.destroy() |
Completely removes the widget, the launcher, and the listeners from the DOM. |
widgetController.showChat() |
Returns immediately to the main chat screen. |
widgetController.registerPage(page) |
Registers a custom interactive page within the widget. |
widgetController.showPage(pageId, props) |
Shows a registered custom page or a built in page, such as the transcript page. |
What do you need to change when migrating from the old widget?
Update the script URL when migrating
Migrating from the old widget to the new, component-based widget? Then update the script's src attribute: from the old location at obistatic.s3.../ngbots/... to https://cloudstatic.obi4wan.com/chatplus/obi-launcher.bundle.js.
Features such as the renewed URL blacklist and the advanced SPA route monitoring only work with this new script bundle, and the preview in the Chat+ dashboard already shows the new, component-based widget by default.