Customize Guide Using APIs

To use Guide with your website, you can simply embed Guide on each page of your website where you want to offer an engagement.

However, if you are familiar with web development, and you would like to make customizations to the appearance and behavior of the Guide widget, you can do so by using APIClosed APIs allow you to automate certain functionality by connecting your CXone system with other software your organization uses. calls to the JavaScript code. These are the types of changes that you can make:

  • Guide widget appearance and behavior: Customize the appearance and behavior of the Guide widget. This includes changing the size of the widget, changing the size of the buttons, displaying the widget in full screen mode, and so on.

  • Chat preferences when offered in Guide widget: Customize the appearance and behavior of chat when offered in the Guide widget. This includes changing the information in the chat window, changing the chat window appearance, setting custom CSS, and so on.

  • Reporting preferences: Customize how Guide tracks engagements and conversions. You can use these APIs when defining custom events, storing visitor variables, storing conversion data, assigning and removing web tags, and so on.

Understanding How Guide Works

The Guide widget is a web module that CXone Loader loads onto your website. The web module contains a JavaScript application that is built using the Svelte framework. The application uses basic state stores that keep track of Guide configuration, the active template, the active chat status, the UI state, and so on. The values of these state stores drive what is displayed to the visitor.

When you embed Guide on a page of your website, and a visitor views the page, Guide fetches the configuration specific to your tenant. This request returns a JSON result with rules, buttons, entry points, translations, referenced articles, and feature flags. It then uses the bundled rules engine to process the rules and conditions that may or may not result in a template or proactive offer appearing on the page.

To manage visitor data between page reloads, Guide uses local and session storage. This allows Guide to provide cross-domain support on supported browsers. It also means that Guide does not use any browser cookies.

Set up Guide customizations in a test environment before releasing them into your production environment. This will help minimize disruptions to your website visitors. It will also help ensure that your customizations work as intended.

Adding JavaScript Calls

  1. Click the app selector and select ACD.

  2. Go to Digital > Points of Contact Digital.

  3. Under Your Channels, click Website Script.
  4. Copy the JavaScript code from the page and paste it into your code or a text editing program. Be sure to include the opening and closing <script> tags.

  5. Just above the closing </script> tag of the code you pasted, add the JavaScript calls to use. In the following example image, the comment indicates where to add calls.

    An example script that shows where to add JavaScript calls

    The Guide JavaScript calls that you can use are described below on this page as well as the Guide chat-related APIs and the Guide reporting-related APIs.

  6. Copy and paste the entire script, including the opening and closing <script> tags, into the header of a page of your website.

  7. Visit the modified page and make sure that the Guide customizations work as intended.

  8. When it is fully tested and works as expected, copy the final script into the header of each page that should have this Guide customization.

Customize the Guide Widget

This call lets you adjust the Guide widget appearance and behavior.

Adjust the CSS

Changes the CSS elements for the Guide widget. For example:

cxone('guide', 'setCustomCss', '[data-selector="GUIDE_ELEMENT"] {background: red !important;}');

To use this snippet, replace GUIDE_ELEMENT with a value from the following table and replace the example CSS in curly brackets { } with your custom CSS:

Guide interface

GUIDE_ELEMENT values
Guide widget and buttons

  • GUIDE_CHANNEL_BUTTON

  • GUIDE_CHANNEL_BACK_BUTTON

  • GUIDE_SINGLE_MENU_CLOSE_BUTTON

  • GUIDE_MULTIPLE_MENU_CLOSE_BUTTON

  • GUIDE_CUSTOMER_PORTAL_CLOSE_BUTTON

  • GUIDE_FRAME_CONTENT

  • GUIDE_CHANNEL_ICON

  • GUIDE_CHANNEL_MENU_ICON
Portals

  • PORTAL_HEADER_iCON

  • PORTAL_HEADER

  • PORTAL_TITLE

  • PORTAL_SUBTITLE

  • GUIDE_CHANNEL_BUTTON_1

  • GUIDE_CHANNEL_BUTTON_2

  • GUIDE_CHANNEL_BUTTON_3

  • GUIDE_CHANNEL_BUTTON_4

  • GUIDE_MENU_BUTTON

  • KB_WIDGET_TITLE

  • KB_WIDGET_SEARCHBAR

  • KB_SEE_MORE_BUTTON

  • PORTAL_BODY

  • KB_WIDGET

  • CHANNELS_WIDGET
Articles

  • KB_HEADER

  • KB_BODY

Chats and emails

  • PRECONTACT_SURVEY

  • BEGIN_CHAT

  • SEND_EMAIL

  • INPUT

  • TEXTAREA

  • DROPDOWN

  • TREE

  • PRECONTACT_SURVEY_DESCRIPTION

  • PRECONTACT_SURVEY_ICON

  • TREE_POPUP_BACK_BUTTON

  • CLOSE_TREE_POPUP

  • CLOSE

Proactive offers

  • OFFER_CLOSE_BUTTON

  • OFFER_HEADER

  • OFFER_BODY

  • OFFER_BUTTON_1

  • OFFER_BUTTON_2

  • OFFER_BUTTON_3

Adjust Channel Button Size

Sets the size to use for channel buttons. Enter a value in ems or pixels. The default button size is 3em. 

cxone('guide', 'setButtonSize', '80px');

Adjust Channel Button Offset

Sets the offset value to use for channel buttons. Enter a value in ems or pixels.

cxone('guide', 'setOffsetX', '48px');
cxone('guide', 'setOffsetY', '3em');

Open Guide Menu

Displays the Guide menu of buttons.

cxone('guide', 'openMenu');

Close Guide Menu

Closes the Guide menu of buttons.

cxone('guide', 'closeMenu');

Change Font Size

Sets the default font size used in the Guide widget. Enter a value in pixels. The default font size is 13 pixels. The value set here determines the em size used throughout Guide.

cxone('guide','setFontSize',12);

Change Height of Guide Widget

Sets the height of the Guide widget. Enter a value in ems or pixels. The default height is 40em. The maximum height is 40 rem.

cxone('guide','setDesiredGuideHeight','30em');

Change Width of Guide Widget

Sets the width of the Guide widget. Enter a value in ems or pixels. The default width is 23.125em.

cxone('guide','setDesiredGuideWidth','608px');

Display Guide in Full Screen Mode

You can display Guide in full screen mode. Guide content appears in a window instead of the Guide widget.

cxone('guide','setFullDisplay');

A best practice when in full screen mode is to hide the minimize button. To do so, use the following commands:

cxone('guide','setFullDisplay');
cxone('guide', 'setCustomCss', '[data-selector="GUIDE_CHANNEL_CLOSE_BUTTON"] {display: none !important;}');

Omit the Chat Precontact Web Survey

Use this API to instruct Guide to start a chat without displaying the precontact web survey.

cxone('guide','hidePreSurvey');

Use the chat APIs to pre-set precontact web survey values. Alternatively, you can specify them as parameters for the hidePreSurvey API. For example:

cxone('guide','hidePreSurvey', 'Dre', 'dre@classics.com');

Directly Display an Entry Point

Use this API to manually display an entry point in a window. The default button for the entry point is used.

This API is provided for specific cases when someone might need to manually show an entry point in a window. It is not generally recommended, and it should not be used in combination with Guide engagement rules.

To use this API, you must pass the ID of the entry point to display. You can get the entry point ID by clicking Edit next to the entry point and then copying the last part of the page URL. 

cxone('guide','openEntrypoint','e1348160-2016-4d91-958e-fd063c669fe6');