Web Chat

A Genesys Cloud web chat widget allows customers to chat with contact center agents directly from your website.

Note: This web chat widget does not support Altocloud. To use Altocloud use the version 2 widget.

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.

To add a web chat widget, follow these steps:

Add a web chat deployment. See About widgets for web chat on the resource center for more information.
Embed the <script> tag for the Genesys Cloud web chat API generated in Step 1.
To render the chat session, add one of the following snippets inside the chat configuration container.

Frame rendering:

(function(window) {
  window.PURECLOUD_WEBCHAT_FRAME_CONFIG = {
    containerEl: 'chat-container'
  };
  var chatConfig = {
    webchatAppUrl: 'https://apps.mypurecloud.com/webchat',
    webchatServiceUrl: 'https://realtime.mypurecloud.com:443',
    orgGuid: 'YOUR_GUID_HERE',
    orgId: 'YOUR_ID_HERE',
    orgName: 'YOUR_ORGNAME_HERE',
    queueName : 'Support',
    chatNowElement: 'start-purecloud-chat',
    logLevel: 'INFO',
    reconnectEnabled: true,
    reconnectOrigins: [ 'https://example.com' ]
  };

  window.ININ.webchat.create(chatConfig).then(function(webchat) {
    var startChatButton = document.getElementById('start-purecloud-chat');
    startChatButton.onclick = function onStartChatClick () {
      return webchat.renderFrame({
        containerEl: 'chat-container'
      }).catch(function(error) {
        console.error('Error starting chat');
        console.error(error);
      });
    };
  }).catch(function(error) {
    console.error('Error initializing chat');
    console.error(error);
  });
})(window);

Note: In this example, containerEl refers to the id of the chat container div tag. This tag is shown in the example page below.

Popup rendering:

Important

Popup chat in a new window is unsupported with screen share. If you plan to use popup chat with screen share, then you must set newTab to true in the webchat.renderPopup() call so that a popup chat opens in a new tab instead of a new window.

(function(window) {
  var chatConfig = {
    webchatAppUrl: 'https://apps.mypurecloud.com/webchat',
    webchatServiceUrl: 'https://realtime.mypurecloud.com:443',
    orgGuid: 'YOUR_GUID_HERE',
    orgId: 'YOUR_ID_HERE',
    orgName: 'YOUR_ORGNAME_HERE',
    queueName : 'Support',
    chatNowElement: 'start-purecloud-chat',
    logLevel: 'INFO',
    reconnectEnabled: true,
    reconnectOrigins: [ 'https://example.com' ]
  };
  ININ.webchat.create(chatConfig).then(function(webchat) {
  // Render to popup
    return webchat.renderPopup({
      width: 400,
      height: 400,
      title: 'Chat',
      //set newTab to true if using screen share
      newTab: false
    }).catch(function(error) {
      console.error('Error starting chat');
      console.error(error);
    });
  }).catch(function(error) {
    console.error('Error initializing chat');
    console.error(error);
  });
})(window);

To set properties for the chat session, add variables within the chatConfig object. For more information, see below Chat variables.

Chat variables

You can use the following variables in the chat configuration container.

webchatAppUrl- The web chat URL.

North America (N. Virginia ): https://apps.mypurecloud.com/webchat
North America (Oregon): https://apps.usw2.pure.cloud/webchat
Australia/New Zealand: https://apps.mypurecloud.com.au/webchat
EU (Ireland): https://apps.mypurecloud.ie/webchat
EU (Frankfurt): - https://apps.mypurecloud.de/webchat
EU (Zurich): - https://apps.euc2.pure.cloud/webchat
Japan (Tokyo): https://apps.mypurecloud.jp/webchat
Japan (Osaka): https://apps.apne3.pure.cloud/webchat
Seoul: https://apps.apne2.pure.cloud/webchat
Mumbai: https://apps.aps1.pure.cloud/webchat
Sao Paulo: https://apps.sae1.pure.cloud/webchat
Middle East (UAE): https://apps.mec1.pure.cloud/webchat

webchatServiceUrl- The web chat service URL.

North America (N. Virginia ): https://realtime.mypurecloud.com:443
North America (Oregon): https://realtime.usw2.pure.cloud:443
Australia/New Zealand: https://realtime.mypurecloud.com.au:443
EU (Ireland): https://realtime.mypurecloud.ie:443
EU (Frankfurt): https://realtime.mypurecloud.de:443
EU (Zurich): - https://realtime.euc2.pure.cloud:443
Japan (Tokyo): https://realtime.mypurecloud.jp:443
Japan (Osaka): https://realtime.apne3.pure.cloud:443
Seoul: https://realtime.apne2.pure.cloud:443
Mumbai: https://realtime.aps1.pure.cloud:443
Sao Paulo: https://realtime.sae1.pure.cloud:443
Middle East (UAE): https://realtime.mec1.pure.cloud:443

orgId- Genesys Cloud organization ID; a short number such as 987. You can retrieve your org ID as follows:

Use the GET api/v2/organizations/me API call as the thirdPartyOrgId property.
Contact Genesys Cloud support.

orgName- Genesys Cloud organization name. You can retrieve your organization ID with the GET /api/v2/organizations/me API call as the thirdPartyOrgName property or by contacting Support. Example: inin
queueName- The queue name that receives chat messages. Example: 'Support'

Note: You must specify a queueName or agentEmail. If you specify both, agentEmail takes precedence.

agentEmail - The email address for the agent that receives chat messages. Example: 'john.smith@example.com'

Note: You must specify a queueName or agentEmail. If you specify both, agentEmail takes precedence.

showSubmitButton- Whether to show a submit button. If true, users must press the button to send a message. If false, users must press Enter to send a message.
skills-(Optional) List of skills. Example: ['Computers', 'Printers']
priority- Priority level from 0 (lowest) to 10 (highest). Example: 5
language- (Optional) Requested agent language skill. Example: 'English - Written'
welcomeMessage-The message displayed to users when opening a chat. Example: 'Please wait while we connect you to one of our agents.'
maskPatterns- Applies a JavaScript regular expression that hides chat input received from a customer during a chat session, such as confidential information. For example, the entry 5[1-5][0-9] hides numbers between 510 and 559. For more information about regular expressions, see the Javascript Guide.
logLevel- The level of debugging output. You can specify; DEBUG, INFO, WARN, ERROR, or FATAL. Example: 'DEBUG'
locale- The locale code. Specify this option if you plan to localize your widget. Example: 'en'
data- User data provided to the agent when the interaction begins.

{
  firstName: 'John',
  lastName: 'Doe',
  addressStreet: '64472 Brown Street',
  addressCity: 'Lindgrenmouth',
  addressPostalCode: '50163-2735',
  addressState: 'FL',
  phoneNumber: '1-916-892-2045 x293',
  email: 'john.doe@altavista.com',
  phoneType: 'Cell',
  customerId: '59606'
}

You can use the customField and customFieldLabel fields to add up to three custom fields to the data container, as follows:

{
  customField1Label: 'Chat source',
  customField1: 'Billing site',
  customField2Label: 'Customer category',
  customField2: 'Small-medium business',
  customField3Label: 'Customer type',
  customField3: 'Partner'
}

companyLogo- The company logo displayed in the widget.

{
  url: 'https://www.mycompany.com/company-logo.png',
  width: 600,
  height: 149
}

Note: Include this field only for pop-up chat widgets; it is not supported for embedded chat widgets.

companyLogoSmall-Small version of the company logo displayed in the widget.

{
  width: 149,
  height: 149,
  url: 'https://www.mycompany.com/company-logo-small.png'
}

Note: This field requires the welcomeMessage field

agentAvatar-The avatar used for the agent.

{
  width: 462,
  height: 462,
  url: 'https://www.mycompany.com/agent.png'
}

userAvatar- The avatar used for the customer.

{
  width: 300,
  height: 300,
  url: 'https://www.mycompany.com/user.jpg'
}

cssClass-CSS class. Use this option if your website renders the widget as a frame. Example: 'webchat-frame'
css-CSS properties. Use this option if your website renders the widget as a frame.

{
  width: '100%'
}

Chat reconnects

By default, web chat sessions disconnect from the Genesys Cloud agent when the customer navigates to a different page, leaves the site, or refreshes the page.

To enable chat reconnects:

Set the reconnectEnabled configuration property to true.
Call ININ.webchat.create() as soon as the page loads. Reconnects do not work if ININ.webchat.create() is only called on a button click, for example. You can use webchat.isAutoJoined() to check if autojoin was successful.
Define window.PURECLOUD_WEBCHAT_FRAME_CONFIG before calling ININ.webchat.create(). Set its value to an object that contains the name of the webchat container element.
Call webchat.renderFrame() when the start chat button is clicked. Reconnects do not apply to popup chat.

Additional reconnect notes

Chat reconnect is only available for embedded chat, not popup chat.
There is a five minute timeout on chat reconnects. If a customer leaves the page and does not return within five minutes, then the chat session will not reconnect.
By default, reconnects are allowed from the origin that initiated the chat. You can optionally use reconnectOrigins to list additional origins or subdomains that will allow reconnects. For example, if you want to allow a customer's chat to reconnect from example.com, help.example.com, and shop.example.com, then use reconnectOrigins: ['https://example.com', 'https://help.example.com', 'https://shop.example.com']. The protocol is required.

The web chat example includes reconnect setup.

Chat schedules

To define open and closed hours for web chat, see Web Chat schedules.

Chat start and end events

You can optionally add additional code to run when the chat starts, when an agent joins the chat, and when the chat ends. For example, you could open a page with a third-party survey after a chat session ends.

webchat.chatStarted = function () {
  //Code to run when the chat is started
};

webchat.chatConnectedToAgent = function () {
  //Code to run when the chat is connected to an agent
};

webchat.chatEnded = function () {
  //Code to run when chat ends.
};

Updating the configuration

The Webchat configuration can be changed after creation using webchat.updateConfig. Properties on the object passed into the update method will overwrite the corresponding properties on the existing Webchat configuration. Updates must be done before webchat.renderFrame or webchat.renderPopup is called.

Note: Any of the previously listed configuration properties can be changed by updateConfig. Calling updateConfig after calling webchat.renderFrame or webchat.renderPopup will have no affect on web chat.

Example Page with Web Chat

The following is code for a simple web page with a Genesys Cloud web chat widget.

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <title>Genesys Cloud Web Chat Demo</title>
</head>

<body>
    <form id="chatForm">
        <h3>Participant Information- local</h3>

        <table class="webchat-config">
            <tbody>
                <tr>
                    <th>First Name:</th>
                    <td><input type="text" id="first-name" value="John" /></td>
                </tr>
                <tr>
                    <th>Last Name:</th>
                    <td><input type="text" id="last-name" value="Doe" /></td>
                </tr>
                <tr>
                    <th>Agent Email:</th>
                    <td><input type="text" id="agent-email" value="alex.agent@example.com" /></td>
                </tr>
            </tbody>
        </table>
        <button type="button" id="chat-button">Start Chat</button>
    </form>
    <div id="chat-container" style="height:600px"></div>
    <script src="https://code.jquery.com/jquery-3.2.1.min.js" integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4=" crossorigin="anonymous"></script>
    <script
        id="purecloud-webchat-js"
        type="text/javascript"
        src="https://apps.mypurecloud.com/webchat/jsapi-v1.js"
        region="YOUR_REGION"
        org-guid="YOUR_ORG_GUID"
        deployment-key="YOUR_DEPLOYMENT_KEY"
    ></script>

    <script type="text/javascript">

        $(document).ready(function initializeChat () {
            var chatConfig = {
                // Web chat application URL
                webchatAppUrl: 'https://apps.mypurecloud.com/webchat',

                // Web chat service URL
                webchatServiceUrl: 'https://realtime.mypurecloud.com:443',

                // organization GUID
                orgGuid: 'c398ad04-4448-4a91-adeb-fff0ff85c7a7',

                // Numeric organization ID
                orgId: 1234,

                // Organization name. Replace with your org name.
                orgName: 'yourorgname',

                // Requested agent language skill (Agent must have this language skill to receive chat)
                language: 'English - Written',

                // Requested agent skills (Agent must have these skills to receive chat)
                skills: ['Computers', 'Printers'],
                // OR
                //skills: [],

                // Priority
                priority: 0,

                // Queue Name
                queueName : 'Support',

                // Target agent email (OPTIONAL)
                agentEmail: 'alex.agent@example.com',

                // Whether to show submit button or send message on Enter keypress
                showSubmitButton: true,

                // Log level
                logLevel: 'DEBUG',

                // Locale code
                locale: 'en',

                // Whether to allow reconnects
                reconnectEnabled: true,

                //Allowed reconnect origins
                reconnectOrigins: ['https://example.com', 'https://help.example.com', 'https://shop.example.com'],

                // Logo used within the chat window
                companyLogoSmall: {
                    width: 149,
                    height: 149,
                    url: 'https://dhqbrvplips7x.cloudfront.net/webchat/1.0.23/company-logo-small-9c9fe09b.png'
                },
                // Fallback image used for agent if no agent image is defined in the agent's Genesys Cloud profile
                agentAvatar: {
                    width: 462,
                    height: 462,
                    url: 'https://dhqbrvplips7x.cloudfront.net/webchat/1.0.23/agent-e202505f.png'
                },

                // Text displayed with chat window is displayed
                welcomeMessage: 'Thanks for chatting.',

                // CSS class applied to the chat window
                cssClass: 'webchat-frame',

                // Custom style applied to the chat window
                css: {
                    width: '100%',
                    height: '100%'
                }
            };
            var chatButton = document.getElementById('chat-button');

            // Required if reconnects are enabled
            window.PURECLOUD_WEBCHAT_FRAME_CONFIG = {
                containerEl: 'chat-container'
            };

            ININ.webchat.create(chatConfig)
                .then(function (webchat) {
                    // Optionally use isAutoJoined if reconnects are enabled
                    if (webchat.isAutoJoined()) {
                        // Do something to disable chat button
                    } else {
                        chatButton.onclick = function () {
                            var firstName = document.getElementById('first-name').value;
                            var lastName = document.getElementById('last-name').value;
                            var agentEmail = document.getElementById('agent-email').value;

                            // Use getConfig.setConfigProperty() for any web chat configuration property to dynamically set config values.
                            webchat.getConfig().setData({
                                firstName: firstName,
                                lastName: lastName,
                                addressStreet: '64472 Brown Street',
                                addressCity: 'Lindgrenmouth',
                                addressPostalCode: '50163-2735',
                                addressState: 'FL',
                                phoneNumber: '1-916-892-2045 x293',
                                email: 'willie.duit@myspace.com',
                                phoneType: 'Cell',
                                customerId: 59606
                            });

                            //Use the updateConfig function to update batches of properties by passing in a partially filled chatConfig object
                            webchat.updateConfig({
                                agentEmail: 'debrah.agent@example.com',
                                locale: 'es',
                                welcomeMessage: 'Welcome to Example support',
                            });

                            // Alternatively, call webchat.renderPopup here. Note that reconnects do not apply to popup chat.
                            return webchat.renderFrame({
                                containerEl: 'chat-container'
                            });
                        };
                    }
                })
                .catch(function (err){
                    console.log(err);
                });
        });

    </script>

</body>
</html>