Overview

The following documentation outlines the configuration for the connector and how to implement functions specifically for IBM Watson.

Bot Configuration

See the Getting Started guide first to complete pre-requisite steps.

Please note, that Watson does not support processing newline, tab and carriage-return characters. These symbols will be removed from any query that is sent to Watson via the provided connector.

With watson there are two ways of authentication that currently our system support, these are UserPass and IAM (token based) authentication. You can choose one of them for your bot configuration.

UserPass authentication

You will be presented with following screen to complete the Vendor Settings in order to add bot connector using UserPass authentication.

Figure 1.1 Showing the configuration that needed to be filled using UserPass authentication

Following information needs to be completed for LivePerson:

Item Description Example
Workspace URL Watson Assistant Workspace URL https://gateway.watsonplatform.net/conversation/api
Workspace ID Watson Assistant Workspace ID 8671e9a1-xxxx-xxxx-xxxx-xxxxf9dfcb74
Conversation Username Username of the Watson Assistant conversation de0a48a5-9f4f-xxxx-xxxx-xxxxx9856751
Conversation Password password for the Watson Assistant conversation which should be used for the bot Dxxxxxxxxxx1
Version Date Version Date of the Watson API 201X-xx-xx


IAM authentication

You will be presented with following screen to complete the Vendor Settings in order to add bot connector using IAM authentication.

Figure 1.2 Showing the configuration that needed to be filled using IAM authentication authentication

Following information needs to be completed for LivePerson:

Item Description Example
Workspace URL Watson Assistant Workspace URL https://gateway.watsonplatform.net/conversation/api
Workspace ID Watson Assistant Workspace ID 8671e9a1-xxxx-xxxx-xxxx-xxxxf9dfcb74
API key API key which will be used for the Bot's authentication in Watson xxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxZG
Token endpoint url URL for creating/refreshing Watson Assistant tokens Dxxxxxxxxxx1
Version Date Version Date of the Watson API 201X-xx-xx


Test Connection

You have to agree to Data Disclaimer from now onward in order to use the services of bot connector. For that you can click on the checkbox "I agree to the Data Disclaimer

For validation of the credentials provided, you can now perform a test connection request to see if everything that you have provided is working and reachable. You can click on the button "Test Connection" to see if connection succeed or fail. For UserPass authentication see in Figure 1.3 and 1.4. For IAM authentication see in Figure 1.5 and 1.6.

Figure 1.3 Showing the success case of the valid credentials for UserPass authentication

Figure 1.4 Showing the fail case of the invalid credentials for UserPass authentication

Figure 1.5 Showing the success case of the valid credentials for IAM authentication

Figure 1.6 Showing the fail case of the invalid credentials for IAM authentication

Once you are done with providing configuration you can save it by pressing on "Done". Congratulations! You have completed the configuration of the Watson Assistant bot.

Following guide is going to present customization for the Watson Assistant on how to implement functions specifically for IBM Watson. It is intended for users who are familiar with IBM Watson cloud dashboard. Continue if you are familiar and have access to IBM Watson cloud dashboard.

Sending Rich Content (Structured Content)

The core LiveEngage platform supports the use of rich/structured content. For more information on the format and functionality available, please refer to the documentation found here. As a result, the Bot Connector also supports this.

To send structured content via Watson Assistant you will need send custom JSON. To do this, you will need to select the dialog node that will hold the structured content (Figure 2.1).

Figure 2.1 Watson Dialog Node

From there, under the section Then respond with: Click the three vertical dots and select Open JSON Editor (Figure 2.2)

Figure 2.2 Watson Assistant Dialog JSON Editor

In the JSON Editor you will need to add your custom JSON response (Figure 2.3).

Figure 2.3 Watson Assistant JSON Editor

There is a strict JSON structure for the response that must be used. The JSON structure can be found below in Figure 2.4 with a sample JSON example that uses a standard Structured Content card with a button option in Figure 2.5.

{
  "output": {
    "text": {
      "values": [
        {
          "metadata": [
            {
              "id": "1234",
              "type": "ExternalId"
            }
          ],
          "structuredContent": {}
        }
      ],
      "selection_policy": "sequential"
    }
  }
}

Figure 2.4 Structured Content Watson JSON Structure

{
  "output": {
    "text": {
      "values": [
        {
          "metadata": [
            {
              "id": "1234",
              "type": "ExternalId"
            }
          ],
          "structuredContent": {
            "type": "vertical",
            "elements": [
              {
                "type": "button",
                "click": {
                  "actions": [
                    {
                      "text": "Recommend me a movie, please",
                      "type": "publishText"
                    }
                  ]
                },
                "title": "Recommend a movie"
              }
            ]
          }
        }
      ],
      "selection_policy": "sequential"
    }
  }
}

Figure 2.5 Structured Content Watson JSON Example

For new IAM workspaces that have a new Watson response, Then respond with text:

Put the structured content objects with the metadata in the text field for the response.

{
  "output": {
    "generic": [
      {
        "values": [
          {
            "output": {
              "text": {
                "values": [
                  {
                    "metadata": [
                      {
                        "id": "1234",
                        "type": "ExternalId"
                      }
                    ],
                    "structuredContent": {
                      "type": "vertical",
                      "elements": [
                        {
                          "type": "button",
                          "click": {
                            "actions": [
                              {
                                "text": "Recommend me a movie",
                                "type": "publishText"
                              }
                            ]
                          },
                          "title": "Recommend a movie"
                        }
                      ]
                    }
                  }
                ],
                "selection_policy": "sequential"
              }
            }
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

Figure 2.6 Structured Content Watson JSON Example (IAM)

For using quickReplies, we require a special formatting of the structured content. The quick replies rich content should be added to the quickReplies property of the structuredContent object, and also a message should be included. This message will be sent to the customer along with the quick replies. Figure 3.6 Figure 3.7

{  
  "structuredContent": {
    "quickReplies": {
      // insert quickReplies rich content here as described here
      //https://developers.liveperson.com/quick-replies-introduction-to-quick-replies.html
      "type": "quickReplies",
      "replies": [...],
      "itemsPerRow": 8
    },
    "message": "Message to send before sending QuickReplies content"
  },
  "metadata": [
    {
      "id": "1234",
      "type": "ExternalId"
    }
  ]
}

Figure 2.7 Quick Replies StructuredContent structure.

{  
   "output": {
       "text": {
         "values": [
           {
             "metadata": [
               {
                 "id": "1234",
                 "type": "ExternalId"
               }
             ],
             "structuredContent": {
               "quickReplies": {
                 "type": "quickReplies",
                 "itemsPerRow": 8,
                 "replies": [
                   {
                     "type": "button",
                     "tooltip": "yes i do",
                     "title": "yes",
                     "click": {
                       "actions": [
                         {
                           "type": "publishText",
                           "text": "yep"
                         }
                       ],
                       "metadata": [
                         {
                           "type": "ExternalId",
                           "id": "Yes-1234"
                         }
                       ]
                     }
                   },
                   {
                     "type": "button",
                     "tooltip": "No!",
                     "title": "No!",
                     "click": {
                       "actions": [
                         {
                           "type": "publishText",
                           "text": "No!"
                         }
                       ],
                       "metadata": [
                         {
                           "type": "ExternalId",
                           "id": "No-4321"
                         }
                       ]
                     }
                   }
                 ]
               },
               "message": "Do you like Bots?"
             }
           }
         ],
         "selection_policy": "sequential"
       }
     }
}

Figure 2.8 Watson Quick Replies StructuredContent example.

Change Time To Response of Conversation

Change the TTR of a conversation based on the action response of Watson. There have 4 different types. "URGENT", "NORMAL", "PRIORITIZED", "CUSTOM". Only the "CUSTOM" can set a value. The unit of the value is second. And the value of the others are defined in the Agent Workspace.

{
  "output": {
    "text": {
      "values": ["Sure thing! Change the TTR to 50 minutes."],
      "selection_policy": "sequential"
    }
  },
  "actions": [
    {
      "name": "CHANGE_TTR",
      "type": "CLIENT",
      "parameters": {
        "ttrType": "CUSTOM",
        "value": 3000
      },
      "result_variable": "none"
    }
  ]
}

Figure 2.9 Watson JSON response for changing TTR

Transfer/Escalations

Naming Conventions: Before going into actions and skills is the naming convention between each. All non-escalation actions are defined by using underscores. For example, in the case of closing a conversation, the action name returned by Watson needs to be CLOSE_CONVERSATION. Further down the line, if any additional functionality is added that can be called by an action from the AI, it will follow the same naming convention. For escalations, the naming convention for these skills should use a "-" instead of "\_". Furthermore, if transferring to a skill, specifically assigned to bots, it’s best practice to prefix the skill name with "BOT-" within LiveEngage.

Transfers and escalations are straightforward in both chat and messaging. At the beginning of a chat session or when a messaging bot logs in, all the list of enabled skills on the account are retrieved, keyed by name and stored. When a transfer is requested by the bot, the skill name is matched to one already on the account and the id is retrieved and escalated to. In regards to Watson Assistant, this should be configured in the following way:

In the Then respond with: JSON editor block, we see the following:

{
  "output": {
    "text": {
      "values": ["Escalating to a human"]
    }
  },
  "actions": [
    {
      "name": "TRANSFER",
      "type": "client",
      "parameters": {
        "skill": "human_skill"
      },
      "result_variable": "none"
    }
  ]
}

Figure 2.10 Watson JSON response for escalation

Above is the actions array. Here, we have a escalation skill name in the skill parameter. This is the name of our skill for escalation. This will be sent in the BOSO object to the chat/messaging connector, which will grab the skillId from an array based on the name, and escalate.

Close Chat/Conversation

To close a chat or messaging conversation, we utilize the action object as we did for a transfer (see Figure 2.10). In Figure 2.11 below, the Watson Assistant JSON response should be mirrored as follows:

{
  "output": {
    "text": {
      "values": ["Thanks for chatting with us today!"],
      "selection_policy": "sequential"
    }
  },
  "actions": [
    {
      "name": "CLOSE_CONVERSATION",
      "type": "client",
      "result_variable": "none"
    }
  ]
}

Figure 2.11 Watson Assistant JSON response for closing chat/conversation