Jump to: navigation, search

Customizing the Browser Tier Widgets

Deprecation notice

  • Starting with the release of Genesys Web Engagement, Genesys is deprecating the Native Chat and Callback Widgets—and the associated APIs (the Common Component Library)—in preparation for discontinuing them.

    This functionality is now available through a single set of consumer-facing digital channel APIs that are part of Genesys Mobile Services (GMS), and through Genesys Widgets, a set of productized widgets that are optimized for use with desktop and mobile web clients, and which are based on the GMS APIs.

    Genesys Widgets provide for an easy integration with Web Engagement, allowing you to proactively serve these widgets to your web-based customers.

    {{NoteFormat|Although the deprecated APIs and widgets will be supported for the life of the 8.5 release of Web Engagement, Genesys recommends that you move as soon as you can to the new APIs and to Genesys Widgets to ensure that your functionality is not affected when you migrate to the 9.0 release.

    • Note that this support for the Native Chat and Callback Widgets and the associated APIs will not include the addition of new features and that bug fixes will be limited to those that affect critical functionality.

    Genesys Web Engagement includes pre-integrated Browser Tier widgets that are used for engagements. These widgets are based on HTML, CSS, and JavaScript, and can be customized to suit the look and feel of your website.

    If you customize the widget HTML files, they will not be backward compatible with any new versions of Genesys Web Engagement.


    The default invitation approach in Genesys Web Engagement is represented by invite.html (chat invitation). This HTML file, by default, has all the required dependencies embedded to avoid extra requests to the server.

    The invite.html file has three code sections:

    • Initial HTML Section
    • JavaScript Third-party Libraries (dependencies) Section
    • JavaScript Invitation Business Logic Section


    There are four main ways you can customize the invitation widget:

    • HTML/CSS — You can edit the HTML/CSS of your page or the invite.html file.
    • Business Logic — You can modify the business logic included in the invite.html file to work with second- or third-party integration.
    • Notification Service — You can change the JavaScript configuration through the Notification Service REST API.
    • You can build your own version of the invitation. The default invitation widget is an example of a custom-built widget.


    In the paragraphs below, Genesys assumes that you have basic knowledge of CSS and HTML technologies.

    If you need to change the basic style of the invitation (color, company logo, size, and so on) Genesys recommends that you use the HTML/CSS approach.

    By default, the invite widget also contains all of the CSS needed for invite rendering, which is automatically added to the beginning of the <head> section of the web page when the invite is initialized.

    If you need to modify these default styles, but you don't want to make it difficult to upgrade to newer versions of the widget, you can can create custom override styles. Make sure that your overrides are scoped to the components that need additional styling, and structure them so that they don't conflict with or overwrite any stand CSS files.

    When overriding styles, consider the following points:

    1. Review how the classes are assigned in the invite widget markup to better understand how they're applied (and how they can be overridden).
    2. Create an override stylesheet. The best way to safely fine-tune a widget's appearance is to write new style rules that override the invite widget's styles and append these "override rules" in a separate stylesheet. Override rules are written against widget CSS class names and must appear in the source order after your theme stylesheet; since styles are read in order, the last style rule always takes precedence. By maintaining override styles in a separate file, you can customize the widget styles as much or as little as you’d like and still preserve the ability to easily upgrade the widget files as needed and simply overwrite your existing theme stylesheet, knowing that your override rules remain intact. Override rules can be listed in a dedicated stylesheet for overriding default website styles, or if you prefer to limit the number of files linked to your pages (and therefore limit the number of requests to the server), append override rules to the master stylesheet for your entire project.

    To see exactly what you can override, you can use the developer tools that are commonly found in most modern web browsers. Currently, the Web Engagement CSS selector is not documented and there is no guarantee for backward compatibility for future versions of the invite widget.

    Customization Examples

    Change subject, message, buttons caption

    <div title="New Subject" class="gpe-helper-hidden gpe-dialog">
        <div class="gpe-branding-logo"></div>
        <div class="my-message-content">
            <span>New Message</span>

    Change colors (message, subject, background, and so on)
    For example, if you want to change the dialog style to red colors, you can add these styles to your page:

        .gpe-dialog .gpe-dialog-titlebar {
            background-color: red;
        .gpe-dialog .gpe-button-text {
            color: red;

    Or message color:

        .gpe-dialog .message-content {
            color: blue;
            background-color: red;

    Or inline customization:

    <div title="Chat" class="gpe-helper-hidden gpe-dialog">
        <div class="gpe-branding-logo"></div>
        <div class="message-content" style="color: #ffcc00; background-color: #0066ff "></div>

    Size of Invitation Widget
    To change the size (width and height) of the invite widget, you can use following snippet:

        .gpe-dialog {
            width: 300px !important;
            height: 200px !important;

    Branding Logo
    To customize the branding logo, you can use the CSS class "gpe-branding-logo". By default, the invite.html file uses an embedded image resource with a Data URI Scheme ( http://en.wikipedia.org/wiki/Data_URI_scheme) in base64 format:

    <div class="gpe-branding-logo" style="
        background-image: url(data:image/png;base64,iVBORw0KGgoAAAAN  ...  AAASUVORK5CYII=);

    To customize the logo, you can generate the same base64 data code for your own image with the generator ( http://base64converter.com/).

    Alternatively, you can just use CSS:

    <div class="branding-content" style=" background-image:url('myLogo.png'); "></div>

    Business Logic

    The invite.html file includes functions that you can change or replace for second- or third-party media integration:

    • init()
    • startChat()
    • sendInviteResult()
    • onAccept()

    Generally, you will need to work inside the startChat() function, but you can also make additional changes in other functions. For example, if you need to integrate another type of media besides chat, you can use onAccept() to extend the number of medias the invite supports. You must also be sure to make any necessary changes in the Engagement Logic Strategy.

    Customization Examples

    Notification Service

    The Notification Service is used to pass data to the invitation from the server. By default, data is composed in the engage.workflow of the Engagement Logic Strategy (apps/application name/resources/_composer-projects/WebEngagement_EngagementLogic/Workflows/engage.workflow).

    You can use predefined commands in the Notification Service REST API to show your own invitation — particularly, gpe.callFunction and gpe.appendContent.

    Customization Examples


    You can localize the invite by using the Chat Invitation Message. Use the subject, message, acceptBtnCaption and cancelBtnCaption options to set specific text for the invite widget.


    The chat widget provides the main chat functionality for Genesys Web Engagement. It's a versatile widget that can be customized through the Chat Service JS API and the Chat Widget JS API.


    There are three different customization types available for modifying the chat widget UI: Template-based, CSS-based, and JavaScript-based. Using these customization types, you can do any of the following:

    • modify the structure of the widget
    • add content
    • add css classes
    • modify the style (including the logo and buttons)
    • use JavaScript UI hooks to modify the widget

    For details about the customization types and how you can use them, see Customizing the User Interface, part of the Chat Widget JS API.

    You can also use the Chat Service JS API to build your own chat widget and control chat sessions. Before creating your own chat widget, be sure to review the default chat widget — it's highly customizable through the Chat Widget JS API, and it also provides access to the same Chat Service JS API.


    You can use the startChat and restoreChat methods of the Chat Widget JS API to enable localization for the chat widget. For details and step-by-step instructions, see Localization.

This page was last edited on March 10, 2020, at 13:56.
Comments or questions about this documentation? Contact us for support!