Chat Widget Configurator User Guide

This guide explains how to use the new Chat Widget configurator in OCP Integrations. The configurator centralizes widget setup in a dedicated Chat Widget area, replacing the older configuration approach from the miniApp Chat tab and providing fuller configuration coverage with live preview support.

Overview

The Chat Widget configurator lets you prepare a web chat experience before embedding it into a website. In general, you will use it to:

• Adjust the widget’s visual identity and branding,

• Define how agent and bot profiles appear to end users,

• Control interaction behavior and session handling,

• Configure notifications and footer content, and

• Generate the script needed to place the widget on a website.

Before you begin

Before configuring the widget, make sure you have access to the Chat Widget area in OCP Integrations and the required connection details for your deployment.

You will typically need:

• an API URL for the WebChat service,

• an API key for the target locale or environment,

• Branding assets such as logos, bubble icons, agent images, or bot images, and

• A target website where the generated script will be embedded.

UI tabs and features

Appearance and Branding

This tab controls the overall look and feel of the chat widget. It is where you align the widget with your brand so that it feels native on your website.

Common options in this area include:

• Content: Main content configuration

  • Widget title: the main header text shown at the top of the widget.

  • Subtitle: supporting text under the main title.

• Logo & Bubble Icon:

  • Logo: the brand image displayed in the widget header and, in some cases, also as the conversation avatar when no separate agent or bot avatar is set.

  • Logo alt text: accessibility text for the logo image.

  • Logo border: Toggle whether the logo is displayed with a border or not.

  • Bubble icon: the launcher icon users click to open chat.

  • Bubble alt text: accessibility text for the bubble icon.

• Colors: Select the color theme of the widget. Select a hex code, or click on the color icon to select RGB code or any color from the palette.
  

  

  • Brand color: the primary theme color used across the widget.

  • Background color: the chat window background color.

• Font: A font family to match your website style.

  • Google font: Add any Google font. Used when generating the embed script.

• Locale: the language used by the widget interface, such as English or French.

Agent and Bot

This tab defines how human agents and the bot are presented in the conversation UI. It helps users understand whether they are interacting with automation, a live agent, or both.

You can configure separate profiles for agent and bot, including:

• Name: the display name shown in the conversation.

• Show name: whether the name is visible to the end user.

• Avatar: an image representing the agent or the bot.

Behaviour

This tab controls how the chat behaves during and after conversations. These settings affect user experience, continuity, and session management.

Typical behaviour-related options include:

• Reset button: enables a button that restarts the chat by calling the Restart Chat action.

• Consecutive dialogs: when enabled, users can continue typing after a dialogue ends; when disabled, the input becomes inactive until the chat is restarted.

• Transcript download: enables downloading the conversation transcript as a PDF at the end of a dialogue from the Download Transcript option in the chat menu.

• Data Persistent: Data persists between sessions without page reload.

• Cross-tab sync: determines whether different browser tabs share the same conversation.

• Reopen minimized chat: controls whether a minimized widget automatically reopens across navigation, reloads, or new tabs.

Notifications

This tab configures how the widget alerts users about unread messages.

Available notification options include:

• Show Notification Dot: A notification dot next to the chat bubble indicates that there are new messages.

• Unread count: Shows the number of unread messages. (Requires Bubble indicator on)

• Pulse effect: Animates the chat and notification bubbles to attract attention. (Requires Bubble indicator on)

• Browser tab title alerts: Alternates the page title to indicate new messages.

• Sound Notifications: Plays a notification sound as soon as message is received

• Custom audio source: lets you define a custom sound file instead of the default sound.

Footer

This tab manages the text and branding shown at the bottom of the widget.

Typical footer options are:

• Show footer: enables footer display.

• Footer text: custom text shown in the footer.

• Footer logo URL: optional image displayed in the footer.

Advanced

This tab includes settings used for deeper customization, integration behavior, and data handling.

Common advanced capabilities include:

• Multiple API URLs for failover support.

• URL selection method such as ordered failover or round-robin selection.

• Initialization data passed into the widget when a new dialog starts.

• Persistent data to retain provided data between sessions on an already loaded page.

• Google Analytics integration to track widget events.

• Event callback support for listening to route or dialog events.

• Event subscription support for actions such as open, minimize, or restart.

• Programmatic open, close, and restart methods for custom site behavior.

• Predefined semantics or intent passing through initialization data or URL-driven setup.

Initialization data is useful for sending simple key-value pairs such as customer identifiers, names, or tokens that help personalize the experience.

Webchat Script

This tab provides the script required to embed the configured widget into a website. After configuration is complete, click the Generate Script button, copy the generated JavaScript snippet and paste it into your website’s HTML, preferably near the end of the body.

The generated script typically includes:

• the widget bundle source,

• the root element ID where the widget will mount,

• the config object containing your selected settings, and

• optionally a data object for initialization values.

(function(docElement, tag, rootElementId, bundleSrc, config, data) {
  var body = docElement.getElementsByTagName('body')[0];
  var div = docElement.createElement('div');
  div.id = rootElementId;
  body.appendChild(div);
  var element = docElement.createElement(tag);
  element.src = bundleSrc;
  element.type = 'text/javascript';
  var callback = function() {
    ChatBot.init({ rootElementId, config, data });
  };
  element.onload = callback;
  element.onreadystatechange = function() {
    this.readyState == 'complete' && callback();
  };
  body.appendChild(element);
})(document, 'script', 'root-chatbot', '<redacted URL>', {
  apiUrl: 'YOUR_API_URL',
  apiKey: 'YOUR_API_KEY'
});

Recommended configuration flow

1. Open the Chat Widget configurator in OCP Integrations.

2. Complete Appearance and Branding to match the customer website.

3. Set up Agent and Bot identities.

4. Adjust Behaviour for the desired conversation experience.

5. Enable only the Notifications that fit the customer experience.

6. Add optional Footer content.

7. Review Advanced options for integrations, persistence, tracking, and startup data.

8. Copy the generated code from Webchat Script.

9. Embed the script into the target website.

10. Use the available preview or test option to validate the final result.

Best practices

• Keep branding consistent with the host website, but avoid overloading the widget with too many visual elements.

• Use clear titles, concise subtitles, and recognizable icons.

• Show bot and agent names only when they improve clarity for the user.

• Enable transcript download and feedback only when they support the use case.

• Test behavior across multiple tabs and page reloads if cross-tab sync or reopen settings are enabled.

• Verify notification sound and visual effects in the customer’s browser and accessibility context.

• Prefer automatic delivery through the API URL to stay current with widget updates.

References

• WebChat Integration Guide