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.
1. Login to the Dynamics 365 account for which you want to find the context service URL. Select the App on the upper left besides Dynamics 365.
2. Select and Click Live Assist Settings.
3. Click Continue.
4. Select Settings on the left panel. 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