This document describes how to integrate the chat service of Genesys Cloud (formerly PureCloud) with a Virtual Assistant (VA) using Teneo Web Chat (TWC) and Teneo Engine. With this integration, TWC serves as a frontend to both Teneo Engine and the chat service of Genesys Cloud so the user can start a conversation with the Virtual Assistant and get connected to a Live Chat agent later if needed.

Prerequisites

These instructions assume your Teneo solution is published and that you know the Engine URL.

Setup instructions

Frontend

1. Deploy TWC as per these instructions.
2. Add (the content of) the extensions file twcPureCloudExtension.js somewhere between the file "teneo-web-chat.js" (the TWC core code) and the TWC initialization code, i.e., after the link to "teneo-web-chat.js" and before the code block where window.TeneoWebChat.initialize(...)
   is called (both are explicitly mentioned in the TWC deployment instructions):

1<script src="/path/to/teneo-web-chat.js"></script>
2...
3<script src="/path/to/twcPureCloudExtension.js"></script>
4...
5<script>
6// The TWC initialization code
7...
8window.TeneoWebChat.initialize(...);
9...
10</script>
11

You can optionally assign the following values BEFORE calling window.TeneoWebChat.initialize()

:

1window.TeneoWebChatExtensions.injected.defaults = {
2    // The name of the avatar (string):
3    title: 'My Virtual Assistant',
4
5    // The URL of the default image of the avatar (string):
6    titleIconUrl: './path/to/avatar/image.png',
7
8    // The number of milliseconds in the Virtual Assistant mode
9    // after which the TWC frontend will close (number):
10    feSessionTimeoutMillis: 540000
11};
12

Here, the string-valued properties title

and titleIconUrl

are, respectively, the name and the URL of the avatar image to appear in TWC, both in the Virtual Assistant mode and in the Live Chat mode, in case the agent's name or avatar image are not provided by the Genesys Cloud chat or by Teneo Engine. The value of the titleIconUrl

property can be any valid URL, including a data URL. If any of these properties is omitted, the default TWC title and/or avatar image will be used.

The number-valued property feSessionTimeoutMillis

is the frontend timeout; this is the number of milliseconds that pass without any requests being submitted to the Teneo Engine, after which the backend session is assumed to be about to expire. The frontend will close automatically after this time lapse provided it is in the Virtual Assistant mode. If it is in the Live Chat mode, this property has no effect. If this property is omitted, is null, NaN or is less than 0, the frontend timeout mechanism is deactivated. If this property is used, it is strongly recommended to set its value to 30-60 seconds less than the Teneo Engine timeout (which can be project-dependent, but is usually 10 minutes).

Teneo Engine

Initialization

Do the following global configurations:

1. Upload reqproxy.jsp into the / folder of your solution (not into /views where JSPs are uploaded by default).
2. Add the content of PureCloudChatAux.groovy to the 'Solution loaded' script. When adding it, configure your customer data in the variables clientId
   , clientSecret
   , organizationId
   , deploymentId
   , queueId
   , customerActionId
   , queueStatisticsUrl
   . You will find these variables right after the definition of the class PureCloudChatAux
   in PureCloudChatAux.groovy):

1...
2String clientId = 'your client ID';
3String clientSecret = 'your client secret';
4String organizationId = 'your organization ID';
5String deploymentId = 'your deployment ID';
6String queueId = 'your queue ID';
7String customerActionId = 'your customer statistics action ID';
8String queueStatisticsUrl = 'https://api.mypurecloud.ie/api/v2/integrations/actions/' +customerActionId + '/execute';
9
10PureCloudChatAux.init(clientId, clientSecret, organizationId, deploymentId, queueId, queueStatisticsUrl);
11

Checking agent availability

The Live Chat agent availability can be checked in Teneo Engine with the PureCloudChatAux.getQueueStats()

method. It returns an object containing the following properties:

• agentsLoggedIn
  , the number of Live Chat agents currently logged in;
• queueLength
  , the length of the queue;
• agentsOnQueue
  , the number of the agents on the queue;
• agentsOnQueueIdle
  , the number of the idle agents on the queue.

You can use any of these properties in your checking logic to decide whether the user should be redirected to the Live Chat.

An example:

1def chatQueueState = null;
2try {
3    String accessToken = PureCloudChatAux.getAccessToken();
4    chatQueueState = PureCloudChatAux.getQueueStats(accessToken);
5} catch (err) {
6    println 'Failure checking chat availability: '+err;
7    // Handle the error here:
8    // ...
9}
10
11if (chatQueueState && chatQueueState.agentsLoggedIn > 0) {
12    // Live Chat is available.
13    // Your code to handle it:
14    // ...
15} else {
16    // Live chat is NOT available.
17    // Your code to handle it:
18    // ...
19}
20

Transferring the user to the Live Chat

In order to transfer the user to the Live Chat, your Teneo Engine should simultaneously return to the TWC the output parameters described below.

Obligatory output parameters

• liveChatAuth
  : The value of this output parameter is a stringified JSON object containing all the data needed by the chat service to start the Live Chat. This value is obtained with the following code (the value in question is assigned to the global session variable sLiveChatAuth
  for illustration purposes only and you have to make sure this value makes it to the output parameter):

1def liveChatAuth = null;
2try {
3    String accessToken = PureCloudChatAux.getAccessToken();
4    liveChatAuth = PureCloudChatAux.getChat(accessToken);
5} catch (err) {
6    println 'Failure creating chat start object: '+err;
7    // Handle the error here:
8    // ...
9}
10
11sLiveChatAuth = liveChatAuth ? new groovy.json.JsonBuilder(liveChatAuth).toString() : '';
12

The fact the output parameter liveChatAuth

is returned is the indication to the TWC to start the handover process.

• liveChatMsgConnectionFailure
  : the message to be displayed in the frontend if the chat connection failed. It is supposed to be returned together with liveChatAuth
  . If it is not, a default message in English ("Failure starting live chat") will be used.

Optional output parameters

• liveChatMsgConnecting
  : the message to be displayed when the frontend tries to establish connection with the Live Chat service as a result of receiving the data in liveChatAuth
  .
• liveChatAgentName
  : the name of the Live Chat agent to display if the Live Chat service has not returned a name.
• liveChatAgentIcon
  : the URL of the avatar image of the Live Chat agent to display if the Live Chat service has not returned any image. It may also be a data URL.
• liveChatMsgClosingChat
  : the message to be displayed in the frontend when the Live Chat agent closes the conversation with the user.
• liveChatFrontendCloseDelayMillisUponAgentLeave
  : the number of milliseconds to wait before closing the frontend as a result of the Live Chat agent closing the conversation with the user. If this value is not defined, it will be 5000 milliseconds. During this time, the message of liveChatMsgClosingChat
  (if it has been returned) will be displayed.
• askCloseLiveChat
  : the confirmation dialog to appear if the user clicks the close button of the frontend in the Live Chat mode. The goal of this dialog is to prevent the user from accidentally closing the Live Chat. Regarding its format, see the description of the add_message
  method in the TWC API. A possible value can be as follows:

1{
2    "type": "modal",
3    "data": {
4        "title": "Confirm",
5        "text": "Do you really want to close the chat?",
6        "button_items": [
7            {
8                "style": "secondary",
9                "title": "Yes, close it!",
10                "postback": "close",
11                "operation": "closeFrontend"
12            },{
13                "style": "secondary",
14                "title": "Cancel",
15                "postback": "cancel",
16                "operation": "cancel"
17            }
18        ]
19    }
20}
21

Additional convenience functionalities

There are several other output parameters that can be used for some convenience functionalities.

• reset
  : If this output parameter is not empty, it causes the frontend to close, terminating the Virtual Assistant backend session.
• minimize
  : If this output parameter is not empty, it causes the frontend to minimize without terminating the Virtual Assistant backend session.
• closingFeedback
  : the confirmation/feedback dialog to appear if the user clicks the close button of the frontend in the Virtual Assistant mode. Regarding its format, see the description of the add_message
  method in the TWC API. A possible value can be as follows:

1{
2    "type": "modal",
3    "data": {
4        "title": "FEEDBACK",
5        "text": "Have you received the answer you were looking for?",
6        "button_items": [
7            {
8                "style": "secondary",
9                "title": "Yes",
10                "postback": "yes",
11                "parameters": {
12                    "command": "userFeedback",
13                    "feedbackRating": "positive",
14                    "abortActiveFlows": "true"
15                }
16            },{
17                "style": "secondary",
18                "title": "No",
19                "postback": "no",
20                "parameters": {
21                    "command": "userFeedback",
22                    "feedbackRating": "negative",
23                    "abortActiveFlows": "true"
24                }
25            },{
26                "style": "secondary",
27                "title": "Close anyway",
28                "postback": "close",
29                "operation": "closeFrontend"
30            },{
31                "style": "secondary",
32                "title": "Cancel",
33                "postback": "cancel",
34                "operation": "cancel"
35            }
36        ]
37    }
38}
39