Widget - Version 2

This article explains how to deploy Genesys Widgets (also known as widget version 2) on your website. See About widgets for web chat on the Resource Center for more information.

Note: To use screen share or co-browse use the version 1 widget. Genesys Widgets do not currently support Genesys Cloud's screen share or co-browse.

Try the Web Chat dev tool!

Try out web chat in your Genesys Cloud organization right in your browser without writing any code using the Web chat/messaging Tools.

Deployment procedure

The deployment procedure involves the following tasks:

Create a new widget deployment in Genesys Cloud.
Obtain your organization id.
Create a widget configuration object.
Deploy the widgets' code snippet to your web pages.
Start the chat.
Advanced configuration (optional)

To create a new widget deployment, see Create a widget for web chat and follow the instructions for Version 2.

As a result of creating a new widget deployment, you should take note of the deployment key that is auto-generated. The deployment key is a randomly generated string of 32 alpha-numeric characters that uniquely identifies your widget. In the next task, you will need to copy and paste this into the deploymentKey field of your configuration object.

Removing Road Network Speed Bumps

Obtain your Genesys Cloud organization ID

This task requires you to have necessary admin permissions to access your Organization Settings. You can follow instructions here: FAQ: How do I find my organization ID? Similarly to the deployment ID, the organization ID is also represented as a string of 32 alpha-numeric characters, separated by hyphens into 5 groups.

Collecting Meteor Particles

The widget loaded on your web page will look for a local configuration object that should be loaded by your page prior to the actual widget JavaScript library. The configuration object is created with JSON syntax and can either be stored as a separate file (fetched at runtime) or defined inline within your page's HTML structure, enclosed in script tags. We recommend using a separate .js file to store the configuration object.

Below is a sample file, which you could edit and store directly in your website structure or make it accessible through your Content Delivery Network (CDN). For example, save the file as widgets.config.js (or choose a different name).

Widgets Configuration Object

window._genesys = {
  widgets: {
    webchat: {
      transport: {
        type: 'purecloud-v2-sockets',
        dataURL: 'https://api.mypurecloud.com',     // replace with API URL matching your region
        deploymentKey : 'YOUR_DEPLOYMENTKEY_HERE',  // replace with your Deployment ID
        orgGuid : 'YOUR_ORGGUID_HERE',              // replace with your Organization ID
        interactionData: {
          routing: {
            targetType: 'QUEUE',
            targetAddress: 'YOUR_QUEUENAME_HERE',
            priority: 2
          }
        }
      },
      userData: {
        addressStreet: '64472 Brown Street',
        addressCity: 'Lindgrenmouth',
        addressPostalCode: '50163-2735',
        addressState: 'FL',
        phoneNumber: '1-916-892-2045 x293',
        phoneType: 'Cell',
        customerId: '59606',
        // These fields should be provided via advanced configuration
        // firstName: 'Praenomen',
        // lastName: 'Gens',
        // email: 'praenomen.gens@calidumlitterae.com',
        // subject: 'Chat subject'
      }
    }
  }
};

Chat configuration variables

Replace the following variables in the chat configuration:

type - always set to 'purecloud-v2-sockets' for use with Genesys Cloud
dataURL - The Genesys Cloud web chat service URL for your region. A list of API URLs per region is available in the Platform API section.
deploymentKey - Genesys Cloud widget deploymentKey. Identifies the widget on your web page as the one you created in the previous task (Create a widget configuration object).
orgGuid - Genesys Cloud organization ID; a unique GUID. You can retrieve your org ID using one of the following methods:

In the Genesys Cloud app under Account Settings, click Organization Settings. On that page, click Advanced and use the value in the Organization ID box as the orgGuid property. (This is described in the previous task, obtain your organization ID.)
Make an API request to GET /api/v2/organizations/me and use the id property of the response as the orgGuid property.
Contact Genesys Cloud support.

targetType - Always set to 'QUEUE' to route to a queue
targetAddress - The queue name that receives chat messages. Example: 'Support'
priority - Priority level from 0 (lowest) to 10 (highest). Example: 5
skills - (Optional) List of skills. Example: ['Computers', 'Printers']
language - (Optional) Requested agent language skill. Example: 'English - Written'
userData - (Optional) an object of key/value pairs of arbitrary custom data. See below for details.

Custom `userData`

Custom data can be provided with the chat for access via Conversations APIs and Agent Scripts. Attributes will be added as participant attributes on the customer participant in the conversation. The attribute names will be prepended with context.. This means that a userData key of accountNumber would become a participant attribute named context.accountNumber. These attributes can also be accessed in an Agent Script by creating an input variable with the name of the userData key (without the context. prefix).

Note: The fields firstname, lastname, email, and subject should be set when opening the widget, not in userData. If the widget's fields are overridden and these fields are not included as input fields, they may be included in userData.

Custom userData

{
  widgets: {
    webchat: {
      userData: {
        addressStreet: '64472 Brown Street',
        addressCity: 'Lindgrenmouth',
        addressPostalCode: '50163-2735',
        addressState: 'FL',
        phoneNumber: '1-916-892-2045 x293',
        phoneType: 'Cell',
        customerId: '59606',
        // These fields should be provided via advanced configuration
        // firstName: 'Praenomen',
        // lastName: 'Gens',
        // email: 'praenomen.gens@calidumlitterae.com',
        // subject: 'Chat subject'
      }
    }
  }
};

Embed the following HTML code snippet in all your web pages where you want the chat widget to run (scroll content to the right):

<script src="https://apps.mypurecloud.com/widgets/9.0/cxbus.min.js" onload="javascript:CXBus.configure({debug:false,pluginsPath:'https://apps.mypurecloud.com/widgets/9.0/plugins/'}); CXBus.loadFile('path/to/widgets.config.js').done(function(){CXBus.loadPlugin('widgets-core')});"></script>

You should populate src and pluginsPath with the proper URL APIs adequate to your region. The list of regional CDN URLs:

North America (East) - https://apps.mypurecloud.com/widgets
North America (West) - https://apps.usw2.pure.cloud/widgets
North America (Canada) - https://apps.cac1.pure.cloud/widgets
Australia/New Zealand - https://apps.mypurecloud.com.au/widgets
EU (Ireland) - https://apps.mypurecloud.ie/widgets
EU (Frankfurt) - https://apps.mypurecloud.de/widgets
EU (Zurich) - https://apps.euc2.pure.cloud/widgets
UK (London) - https://apps.euw2.pure.cloud/widgets
Japan (Tokyo) - https://apps.mypurecloud.jp/widgets
Japan (Osaka) - https://apps.apne3.pure.cloud/widgets
Seoul - https://apps.apne2.pure.cloud/widgets
Mumbai - https://apps.aps1.pure.cloud/widgets
Sao Paulo - https://apps.sae1.pure.cloud/widgets
Middle East (UAE) - https://apps.mec1.pure.cloud/widgets

This script does the following:

Loads cxbus.min.js. This makes the global CXBus instance available.
Configures CXBus to turn on debug logging and set the path to the Widgets plugin folder.
Load your configuration file, widgets.config.js. (This file is created in the previous task, Create a widget configuration object).
Loads widgets-core. This is the core Genesys Widgets library.

Use this script as a starting point and customize it as needed. Your configuration can be defined inline on the page or loaded as a separate file (as shown in this script).

Warning: Whichever method you choose, you must ensure your configuration is in the page before you load widgets-core. Otherwise, widgets-core cannot read the configuration.

Alternative deployment script for Google Tag Manager

To simplify the deployment process while using tools like Google Tag Manager, you can use the below script to embed Widgets.

Deployment Script for Google Tag Manager

<script>
    var widgetBaseUrl = 'https://apps.mypurecloud.ie/widgets/9.0/',
        widgetScriptElement = document.createElement('script');
    widgetScriptElement.setAttribute('src', widgetBaseUrl + 'cxbus.min.js');
    widgetScriptElement.addEventListener('load', function () {
        CXBus.configure({debug: false, pluginsPath: widgetBaseUrl + 'plugins/'});
        CXBus.loadFile('path/to/widgets.config.js').done(function(){
            CXBus.loadPlugin('widgets-core');
        });
    });
    document.head.append(widgetScriptElement);
</script>

Start the chat

Users can start the chat widget on web pages by clicking on corresponding elements, typically a button. You can use an existing button embedded with the chat widget or create your own.

Invoke the customPlugin.command('WebChat.open') function to start the chat. This can be done inline with a button as shown in this example:

<button type="button" id="chat-button-simple" onclick="customPlugin.command('WebChat.open');">Start Chat (simple)</button>

Embedded chat button

To enable the embedded chat button, you need to preload the webchat widget automatically and turn on the embedded chat widget button. Do this by modifying the initial widget configuration object to include the following code:

Preload Chat Widget and Enable Default Chat Button

widgets: {

  main: {
    preload: ['webchat'],
  },

  webchat: {
    chatButton: {
      enabled: true, // (boolean) Enable/disable chat button on screen.
    }
  }
}

The above configuration shows the default chat button template on screen. If you wish to change the look and feel of the chat button, or tweak its behavior, use the following code for additional configuration:

Preload Chat Widget and Enable Custom Chat Button

widgets: {

  main: {
    preload: ['webchat'],
  },

  webchat: {
    chatButton: {
      enabled: true, // (boolean) Enable/disable chat button on screen.
      template: '<div>Live Chat</div>', // (string) Custom HTML string template for chat button.
      effect: 'fade',         // (string) Type of animation effect when revealing chat button. 'slide' or 'fade'.
      openDelay: 1000,        // (number) Number of milliseconds before displaying chat button on screen.
      effectDuration: 300,    // (number) Length of animation effect in milliseconds.
      hideDuringInvite: true  // (boolean) When auto-invite feature is activated, hide the chat button. When invite is dismissed, reveal the chat button again.
    }
  }
}

Advanced configuration

Chat start and end events

You can optionally add a code to run when the chat starts, when an agent joins the chat, and when the chat ends. You can test the below code from the JavaScript console in your browser or by adding in your configuration file as well. For example, you could open a page with a third-party survey after a chat session ends.

Capture Start and End Events

const customPlugin = CXBus.registerPlugin('Custom');

customPlugin.subscribe('WebChatService.started', function (e) {
  console.log('Chat started', e);
});

customPlugin.subscribe('WebChatService.ended', function (e) {
  console.log('Chat ended', e);
});

Auto-populating and customizing input fields

The pre-chat registration form field can be auto-populated in several ways:

Static configuration of the form property in the widgets configuration object.
Passing a custom formJSON object at runtime in your WebChat.open. For example, when you build a custom button.
Overriding the WebChat.open command, and injecting a custom formJSON object at runtime, using the before() method. This may be the case when you use predefined widget elements, like the embedded chat button.

Customizable pre-chat registration form

The initial pre-chat registration form can be customized, by adding labels and input fields:

Text
Select
Hidden
Checkbox
Textarea

See Customizable Chat Registration Form for more details. This also allows you to pre-populate fields as required by your business.

Customize input fields through configuration object

The sample below shows how to customize the pre-chat registration form by updating the configuration object with a nested form object, which defines an array of input fields and labels. The value property of each input field can be populated as the result of a JavaScript function. You can use this approach to populate fields (including hidden ones) when the page loads. The fields are populated using custom functions that can retrieve data from various sources.

Static Configuration

webchat: {
    form: {
        wrapper: "<table></table>",
        inputs: [
            {  
                id: 'cx_webchat_form_firstname',
                name: 'firstname',
                maxlength: '100',
                placeholder: 'Required',
                label: 'First Name',
                value: 'Benjamin'   // This value can be result of a function
            },
            {
                name: "Page",
                label: "Page",
                value: document.title   // This value is obtained from the page title
            },
            {
                name: "Today",
                label: "Today",
                value: new Date().toISOString().split('T')[0]   // This value is result of local function
            }
        ]
    }
}

Customize input fields with the open command

The sample below shows how to pass a customized formJSON object into WebChat.open command. You can try this from your browser console. The JSON object passed is identical to the previous example. Note that the object name is formJSON rather than form. You would typically use this approach when you create your own chat button, and want to pass custom data at runtime, when the user clicks your customized chat button.

Open Command

CXBus.command('WebChat.open', {formJSON: {
    wrapper: "<table></table>",
    inputs: [
        {  
            id: 'cx_webchat_form_firstname',
            name: 'firstname',
            maxlength: '100',
            placeholder: 'Required',
            label: 'First Name',
            value: 'Benjamin'
        },
        {
        name: "Page",
        label: "Page",
        value: document.title
        },
        {
            name: "Today",
            label: "Today",
            value: new Date().toISOString().split('T')[0]
        }
    ]
}});

Intercept and override data based on before() method

The sample below shows the before() method applied to the WebChat.open command, which allows for manipulation of the input object (in this case, it's the formJSON object) before returning the execution to the original command. This allows for customization to be applied to widgets commands being triggered at runtime.

Sample HTML Button

<!--
Start with Chat Button disabled
Chat Button will be enabled by Widgets' onReady function()
 -->
<button class="chat_button" id="chat_button" onclick="myChatButton()" disabled>
    Click here to start chat
</button>

before() function

// Initiate the Widgets configuration object as needed
// We'll use the onReady function() to enable the chat button
// This is to avoid running WebChat.open while still initialising
window._genesys = {
  widgets:{
    webchat: {
      chatButton: {
        enabled: false
      }
    },
    onReady: function(){
      document.getElementById("chat_button").disabled = false;
    },
  }
};

// Load widgets-core after configuration object
CXBus.loadPlugin("widgets-core");

// Create a plugin (or reuse your own if you have one already)
var oPlugin = CXBus.registerPlugin("myPlugin");

// Use before function to intercept 'WebChat.open' command
// and manipulate the input 'options' object before execution continues
oPlugin.before("WebChat.open", function(options){

  // We'll append an additional form field to the one already added
  // by 'open' command in myChatButton() function triggered by button
  if(options.formJSON)options.formJSON['inputs'].push({name:'email',label:'Email',placeholder:'Required'});

  // Still need to return the 'options' object to continue execution
  return options;
});

// this function simulates 'open' command originated externally, like a button in this case
function myChatButton(){
  CXBus.command('WebChat.open', {
    formJSON: {
      inputs: [{ name: 'firstname', placeholder: 'Required', label: 'First Name' }]
    }
  });
};

The following is code for a simple web page with the Genesys WebChat widget.

Web Page with Genesys WebChat Widget

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Genesys Cloud WebChat Demo</title>
</head>

<body>

  <!--Create a Widgets configuration object-->
  <script type="text/javascript">

    window._genesys = {
      widgets: {
        webchat: {
          transport: {
            type: 'purecloud-v2-sockets',
            dataURL: 'https://api.mypurecloud.com',
            deploymentKey : 'YOUR_DEPLOYMENTKEY_HERE',
            orgGuid : 'YOUR_ORGGUID_HERE',
            interactionData: {
              routing: {
                targetType: 'QUEUE',
                targetAddress: 'YOUR_QUEUENAME_HERE',
                priority: 2
              }
            }
          },
          userData: {
            addressStreet: '64472 Brown Street',
            addressCity: 'Lindgrenmouth',
            addressPostalCode: '50163-2735',
            addressState: 'FL',
            phoneNumber: '1-916-892-2045 x293',
            phoneType: 'Cell',
            customerId: '59606',
            // These fields should be provided via advanced configuration
            // firstName: 'Praenomen',
            // lastName: 'Gens',
            // email: 'praenomen.gens@calidumlitterae.com',
            // subject: 'Chat subject'
          }
        }
      }
    };

   </script>

   <!-- Load CXBus and the widgets-core plugin -->
   <script src="https://apps.mypurecloud.com/widgets/9.0/cxbus.min.js" onload="javascript:CXBus.configure({debug:false,pluginsPath:'https://apps.mypurecloud.com/widgets/9.0/plugins/'}); CXBus.loadPlugin('widgets-core');"></script>

   <!-- Optional: Use CXBus to create plugins, subscribe to events, or call commands -->
   <script type="text/javascript">

    const customPlugin = CXBus.registerPlugin('Custom');

    customPlugin.subscribe('WebChatService.started', function (e) {
      console.log('Chat started', e);
    });

    customPlugin.subscribe('WebChatService.ended', function (e) {
      console.log('Chat ended', e);
    });
  </script>



  <button type="button" id="chat-button-simple" onclick="customPlugin.command('WebChat.open');">Start Chat (simple)</button>

  <script type="text/javascript">
		function getAdvancedConfig() {
			return {
				form: {
					autoSubmit: false,
					firstname: 'Praenomen',
					lastname: 'Gens',
					email: 'praenomen.gens@calidumlitterae.com',
					subject: 'Populated from data'
				},
				formJSON: {
					wrapper: '<table></table>',
					inputs: [
						// Default fields
						{
							id: 'cx_webchat_form_firstname',
							name: 'firstname',
							maxlength: '100',
							placeholder: 'Required',
							label: 'First Name'
						},
						{
							id: 'cx_webchat_form_lastname',
							name: 'lastname',
							maxlength: '100',
							placeholder: 'Required',
							label: 'Last Name'
						},
						{
							id: 'cx_webchat_form_email',
							name: 'email',
							maxlength: '100',
							placeholder: 'Optional',
							label: 'Email'
						},
						{
							id: 'cx_webchat_form_subject',
							name: 'subject',
							maxlength: '100',
							placeholder: 'Optional',
							label: 'Subject'
						},
						// Custom Fields
						{
							id: 'custom_field_1',
							name: 'customField1',
							maxlength: '100',
							placeholder: 'Custom Data',
							label: 'Custom Field 1',
							value: 'My Custom Value'
						}
					]
				}
			};
		}
	</script>
	<button type="button" id="chat-button" onclick="customPlugin.command('WebChat.open', getAdvancedConfig());">Start Chat (with data)</button>
</body>
</html>

Genesys Web Fonts

Google Fonts are now hosted in Genesys Infrastructure. Please Choose the nearest or appropriate region URL based on where you are located and configure it through the downloadGoogleFont and googleFontUrl options in widget configuration object .

Download Google Fonts From Genesys Repository

window._genesys = {
  widgets: {
    main: {
      downloadGoogleFont: true,
      googleFontUrl: 'https://apps.mypurecloud.com/webfonts/roboto.css'
    }
  }
};

Note: By default, Genesys web fonts are loaded from the North America (East) region.

The list of regional CDN URLs for loading Google Fonts from Genesys Hosted Repository:

North America (East) - https://apps.mypurecloud.com/webfonts/roboto.css
North America (West) - https://apps.usw2.pure.cloud/webfonts/roboto.css
North America (Canada) - https://apps.cac1.pure.cloud/webfonts/roboto.css
Australia/New Zealand - https://apps.mypurecloud.com.au/webfonts/roboto.css
EU (Ireland) - https://apps.mypurecloud.ie/webfonts/roboto.css
EU (Frankfurt) - https://apps.mypurecloud.de/webfonts/roboto.css
EU (Zurich) - https://apps.euc2.pure.cloud/webfonts/roboto.css
UK (London) - https://apps.euw2.pure.cloud/webfonts/roboto.css
Japan (Tokyo) - https://apps.mypurecloud.jp/webfonts/roboto.css
Japan (Osaka) - https://apps.apne3.pure.cloud/webfonts/roboto.css
Seoul - https://apps.apne2.pure.cloud/webfonts/roboto.css
Mumbai - https://apps.aps1.pure.cloud/webfonts/roboto.css
Sao Paulo - https://apps.sae1.pure.cloud/webfonts/roboto.css
Middle East (UAE) - https://apps.mec1.pure.cloud/webfonts/roboto.css

Widget - Version 2

Deployment procedure

Create a new widget deployment in Genesys Cloud

Obtain your Genesys Cloud organization ID

Create a widget configuration object

Chat configuration variables

Custom `userData`

Deploy the widget's code snippet

Alternative deployment script for Google Tag Manager

Start the chat

Embedded chat button

Advanced configuration

Chat start and end events

Auto-populating and customizing input fields

Customizable pre-chat registration form

Customize input fields through configuration object

Customize input fields with the open command

Intercept and override data based on before() method

Code sample for web page with Genesys WebChat widget

Genesys Web Fonts

Widget - Version 2

Deployment procedure

Create a new widget deployment in Genesys Cloud

Obtain your Genesys Cloud organization ID

Create a widget configuration object

Chat configuration variables

Custom userData

Deploy the widget's code snippet

Alternative deployment script for Google Tag Manager

Start the chat

Embedded chat button

Advanced configuration

Chat start and end events

Auto-populating and customizing input fields

Customizable pre-chat registration form

Customize input fields through configuration object

Customize input fields with the open command

Intercept and override data based on before() method

Code sample for web page with Genesys WebChat widget

Genesys Web Fonts

Privacy Settings

Custom `userData`