Bot Escalation SDK - Context Service

Introduction

When escalating a chat with a customer to a human agent using the Bot Escalation SDKs, there is certain contextual data that the human agent may find helpful. Data such as customer name, location, device, etc (which the bot may have access to but the human agent may not).

The context service allows bots to set data about chats that they have handled. This data will then become available to agents when they take the chat.

Please note that security around this data is paramount and for this reason, there is a necessary amount of setup to be done in creating and configuring security keys.

See also: Bot Escalation SDK - Advanced - Chat Activities

Keys

Context data is sent to the context service in the form of a signed JWT.

You will need to generate a public/private key pair in order to use the context data functionality. There are many ways to do this; for this example, we will use the OpenSSL command-line tool. RSA keys in PEM format are currently supported.

Running the following commands will give you a public/private key pair

>>Create an x509 certificate (containing public key) and private key.
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt

>>Add the private key and certificate(public key) to a pkcs12 container, use this in Azure 
openssl pkcs12 -export -in certificate.crt -inkey privateKey.key -out cert.p12 -name “My friendly name”

>>Export the public key from the certificate, upload this to Live Assist.
openssl x509 -inform pem -in certificate.crt -pubkey -noout > certificate_publickey.pem

You should use the private key (key.pem) to sign the JWT. The public key should be added to the Context keys area in the admin portal. See below for how to do this.

Select the Context Keys option from the Links menu.

Give the key a name (only used for your reference), paste your public key (this should begin with “-----BEGIN PUBLIC KEY-----”) into the box provided, and click Save Key.

You can add as many keys as you like and they will all be checked against signed JWTs that are sent to the context service until a valid one is found - this is useful if you would like to roll over keys. In this case, you can add a new key that you will be using to sign JWTs in the future (next to the existing key). You can leave these both side by side until you are happy any existing JWTs that has been signed using the old key have expired and then delete the old key.

Please note that once the key is saved, it cannot be edited or viewed for security reasons.

Context Service HostName

Follow the steps below to determine the context service URL for your organization.

Login to the Dynamics 365 account for which you want to find the context service URL. Select the down arrow on the top menu to show the next level of options, select Settings, and select Live Assist.

On the Chat Settings page which appears, check the first part of the Agent Widget URL:

Example: If it starts with:

https://service.na1.liveassistfor365.com

then your Context Service URL is:

https://service.na1.liveassistfor365.com/context-service/context

your Context Service Hostname is:

service.na1.liveassistfor365.com

SDKs

The Javascript and .NET SDKs support passing context data to the context service on chat escalation

Once you have a key pair (and have added the public key to the CafeX admin portal) and the context service URL (see above sections) then you can use the SDKs to make use of the context service.

Supported data attributes

The following list shows the context data attributes which are compatible with the agent chat widget. Any of the below values that are passed to the context service will be displayed to the human agent in the context panel when they take a chat.

{
 "chatActivityId": {
   "value": "string",
   "isAsserted": true
 },
 "skill": {
   "value": "string",
   "isAsserted": true
 },
 "customer": {
   "id": {
     "value": "string",
     "isAsserted": true
   },
   "accountName": {
     "value": "string",
     "isAsserted": true
   },
   "companySize": {
     "value": 1,
     "isAsserted": true
   },
   "email": {
     "value": "string",
     "isAsserted": true
   },
   "firstName": {
     "value": "string",
     "isAsserted": true
   },
   "lastName": {
     "value": "string",
     "isAsserted": true
   },
   "language": {
     "value": "string",
     "isAsserted": true
   },
   "os": {
     "value": "string",
     "isAsserted": true
   },
   "country": {
     "value": "string",
     "isAsserted": true
   },
   "city": {
     "value": "string",
     "isAsserted": true
   },
   "isp": {
     "value": "string",
     "isAsserted": true
   },
   "device": {
     "value": "string",
     "isAsserted": true
   },
   "sourceUrl": {
     "value": "string",
     "isAsserted": true
   },
   "ipAddress": {
     "value": "string",
     "isAsserted": true
   }
 },
 "browser": {
   "userAgent": {
     "value": "string",
     "isAsserted": true
   },
   "version": {
     "value": "string",
     "isAsserted": true
   },
   "type": {
     "value": "string",
     "isAsserted": true
   },
   "pageHistory": [{
     "url": {
       "value": "string",
       "isAsserted": true
     },
     "title": {
       "value": "string",
       "isAsserted": true
     },
     "startTime": {
       "value": "string",
       "isAsserted": true
     }
   }]
 }
}

Authenticated Chats

When the bot escalates, the following attribute of the Context Data must contain a ContactID retrieved from the Microsoft Dynamics CRM to authenticate chats the agent receives:

{
    "customer": {
        "id": {
            "value" : <contactid>,
            "isAsserted": true
        }
    }
}

'contactid' values can be determined by using the contacts endpoint in the CRM Web API:

[CRM_URL]/api/data/[API_VERSION]/contacts