Customize the Guide Widget Using APIs

You can customize the Guide widget appearance and behavior using these JavaScript APIs.

Adjust the CSS

Changes the CSS elements for the Guide widget. Make all CSS changes in a single call. A second call overrides the changes from the first call.

Example syntax:

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

To hide a data selector, use display:none. For example, to hide the Guide menu button:

cxone('guide', 'setCustomCss', '[data-selector="GUIDE_MENU_BUTTON"] {display: none;}');
Guide interface data selectors
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;}');

Hide the Chat Precontact 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', {email: "dre@classics.com"});

Set Custom Field Values for Precontact Survey

Use this API to set values for custom fields that appear in a precontact survey. You can set values for the following:

  • Name

  • Any contact custom field

  • Any customer custom field

You can mark a custom field value as hidden:true. The precontact survey form does not display the hidden field. But the value you set for the hidden field is passed to the chat window.

For custom fields not marked as hidden:false, Guide presets the custom fields in the precontact survey with the values specified by the API command. The visitor can use the default values or change them to their liking.

The following syntax example shows how to specify a name that is hidden and passed directly to chat:

cxone('guide','setCustomFields', customerName: {value:"Francis", hidden: true});

The following syntax example shows how to specify two contact custom field values. The email value is hidden in the precontact survey and passed directly to chat. The address value is visible and can be edited in the precontact survey.

cxone('guide','setCustomFields', 
contactCustomFields:[
{ident:email', value: 'josey@nice.com', hidden:true}, 
{ident: 'address', value: '123 Main St', hidden:false}
]);

The following syntax example shows how to specify a customer custom field:

cxone('guide','setCustomFields', 
contactCustomerFields:[
{ident: 'email', value: 'kaya.sanchez@acme.com'}
]);

The following syntax example shows how to specify both a contact custom field and a customer custom field:

cxone('guide','setCustomFields', 
contactCustomFields:[{ident:email', value: 'josey@nice.com', hidden:true}, {ident: 'address', value: '123 Main St', hidden:false}], contactCustomerFields:[{ident: 'email', value: 'kaya.sanchez@acme.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');