The Context Service is part of the Live Assist for Microsoft Dynamics 365 SDK (Live Assist SDK). The Context Service allows bots to build contextual information about their engagements with visitors so that it can be made available to Agents within the CRM when the chat is escalated. The Bot must collect the Context Data before sending it to the Context Service. The Context Data collects asserted visitor details and information about the visitor's interaction on your website.
The Context Data can also include a Chat Activity ID for a Chat Activity that the bot has created. When the chat is transferred to an agent the Chat Activity will be available to the agent and reporting systems within Dynamics CRM.
The steps to implement the bot service are:
- Step 1 — Create a Basic C# Bot
- Step 2 — Import Live Assist Escalation SDK Code Changes
- Step 3 — Generate and managing a public/private key pair for the Context Service
- Step 4 — Loading the Public Key into the Live Assist Admin Portal
- Step 5 — Setting up the Certificate
- Step 6 — Testing the Bot
- Step 7 — Debugging the Bot
Step 1 — Create a Basic C# Bot
In this example, we created an Echo Bot as per https://docs.microsoft.com/en-gb/azure/bot-service/bot-service-quickstart-create-bot?view=azure-bot-service-4.0&tabs=csharp%2Cvscode
However you could add Live Assist Bot enabler capabilities to a QnA bot or any other bot.
Step 2 — Import Live Assist Escalation SDK Code Changes
In this section, we will extend the bot code to:
- Make Echo Bot create context data for a visitor chat.
- Enable the bot to create a Chat Activity within CRM to add to the context data.
- Encrypt the data and pass it to the Live Assist Context Service.
- Enable the Live Assist Context Service to collect the context data.
- Escalate the chat.
- Pass messages between the visitor and the agent once the chat is escalated.
From the command line add the following dependencies to the project you created in step 1:
dotnet add package LiveAssistBotSDK
dotnet add package Jose-jwt
dotnet add package Xrm.Tools.CRMWebAPI --version 1.0.25
dotnet add package Newtonsoft.Json
Alternatively, you can also add packages from Microsoft Visual Studio, select "Manage Nuget Packages, and then search for the package to install e.g:
Extended code snippets for this example are in our Git Repository
Applying Live Assist code changes to the Echo Bot
The complete sample code is at https://github.com/CBA-LAD365/la-kb-snippets/tree/master/EnablerEchoBot-v4/WebAppBot-v4/c%23%20example/ContextService%20examples
You can add this code to your bot project. The EchoBot.cs file can be used to replace your existing EchoBot.cs file.
Note: To inject the IHttpClientFactory into your bot add services.AddHttpClient(); line to the ConfigureServices(IServiceCollection) method in your bot Startup.cs file
The EchoBot.cs code does the following:
1. Adds variables for environmental and chat state along with using declarations.
2. In the existing OnMembersAddedAsync method, creates the instance of the LiveAssist SDK providing the Context Data Host, as well as the LA365 Account Number. We also need to instantiate the botChatStartTime ahead of use:
3. In the existing OnMessageActivityAsync method when the bot receives a visitorMessage:
- Checks if the escalation has started, if so posts a message to the agent.
- If not, it adds the message to the transcript (which will eventually be passed to the agent)
- It then checks if the visitor is requesting to speak to an agent by checking for the String "transfer" in the message. If so it escalates the chat.
- If not, it adds the bot's response to the transcript and then responds to the visitor.
3. Adds an Escalate method that:
- Creates a chat activity via the CreateLiveAssistActivity method.
- Creates a ConversationReference that can be used later to help send messages to the agent.
- Creates a LiveAssist ChatSpec object to pass to the chat escalation, it includes a targeted agent skill, visitor name that will appear to the agent, the transcript of the chat so far and other context data.
- Start timer to poll for Live Assist chat events as it will need to sit in the middle of the chat between the visitor and agent passing messages back and forth.
- Request a chat via the SDK
4. Adds an onTimeEvent method to poll for messages from the Agent and pass them to the visitor.
5. Adds a CreateLiveAssistActivity and GetCRMWebAPI helper methods which authenticate against the CRM to create the Chat Activity. See https://support.liveassistfor365.com/hc/en-us/articles/360006209673 for more information on how to authenticate.
6. Adds a CreateJwt helper method which constructs the context data for the chat being handled. It should only contain a ChatActivity Id and a contactId within the customer object.
A Full list of Context Data attributes is listed in our Context Service Introduction article. A common list of attributes is found within the ContextData.cs file on this example, although these are not needed if you are creating your own Chat Activity.
The Jwt and ContextData used in this method are two helper classes. They are located in the Git Repository along with the rest of the quick-start code. This code relies on additional classes found in the repository.
The Jwt class loads a certificate store so that the Context Data can be encrypted and securely transmitted to Live Assist and the Context Service.
The Jwt class has 2 methods to load the private key and encode the Context Data:
The Create method is the recommended approach for loading certificate stores in code, as it does not rely on the developer having access to the private key. The certificate store can be retrieved from the Azure bot framework using a fingerprint. The process is outlined in the Microsoft Azure App Service Documentation.
A CreateFromFileKey method is also provided for testing. The keys for both methods can be created as per step 3 below:
Step 3—Generate and managing a public/private key pair for the Context Service
Each bot must create its own public/private key pair so that it can encrypt the Context Data sent to the Live Assist Context Service. Your Live Assist organization must be provided the public key to decrypt the data.
There are numerous ways to generate private keys, so the following is only provided as an example. Please be familiar with the common certificate and certificate-store file extensions such as (pem, crt, cer and .pfx). This example uses a self-signed certificate pair generated with OpenSSL. Developing bots may require different RSA keys or provide certificates signed by your organization's CA.
// Create the Private Key specify a CN. openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt Common Name (eg, your name or your server's hostname) []:cafex.example.com //Create a Certificate Store and assign it a password openssl pkcs12 -export -in certificate.crt -inkey privateKey.key -out certificate_store.pfx Enter Export Password: XXXX // Retrieve the Public Key for decryption openssl x509 -inform pem -in certificate.crt -pubkey -out certificate_publickey.pem -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5DJvO/+PZ3H/DP2E09Vp 6ocS7+p0d6ERR/TZNZoT3e3kYnH79bsue/HNz+IJRCk2zCFNVszkF9+iB/JDDQE2 7/gvl0tah8vnfFirr5g3zs1lCkIhEgnJ1reUeRMG/azyn4ZRY+6Fug/AvQqihMLO VI5fw8pql2ZjSwQHWS+aEuFXqlgOQ8VNjIxVx3Zk1BvABfgQbTmt5hLa9YSyhXQp Ln/0XHTnNMEQEsWbA6iK3UdS2/M7/ejNeA2pAIk2HJE4GDpsBo2yBaBQE7vzdJKw smyrLYXm7ws25opElnNbYgy99KXDtYMTP6/cOyouXSgvpWlSeSZrAG597kQyJQE+ nwIDAQAB -----END PUBLIC KEY----- //Fingerprint/Thumbprint needed for certificate identification openssl x509 -in certificate.crt -fingerprint -noout SHA1 Fingerprint=AA:78:DF:90:3B:DF:B7:34:BE:A8:9E:E4:C5:35:F4:BB:E8:5A:1A:5C
Step 4 — Loading the Public Key into the Live Assist Admin Portal
Your Live Assist organization needs access to the Public Key to access the Context Store. Keys can be added via the Live Assist Admin Portal.
Please read How to Log into the Admin Portal if necessary.
From the Admin Portal select Link > Context Keys
On the following page, you can provide a name for the Public Key and then paste in the key you collected in the previous step.
The Public Key name can be anything, but we would recommend using the Bot's Name and/or the certificate Fingerprint to identify it.
Step 5 — Setting up the Certificate
As described in step 3, the certificate needs to be loaded into Azure. The Azure App Service Documentation provides an article on Managing and Loading SSL Certificates .
Important: You must set the WEBSITE_LOAD_CERTIFICATES setting:
SSL Settings are only available on Basic+ Pricing plans. From the App Service - SSL Settings tab you can upload a new Certificate:
You can then upload the PFX file, using the password created in Step 3:
You can then see the private certificate and corresponding thumbprint:
This should be the same as the fingerprint produced in Step 3 and specified in the Jwt.csx code.
Step 6 — Testing the Bot
The Bot can be tested from the Azure Bot Services, which is exactly how the Web Chat was tested in the previous Web App Bot.
The Agent will now see the Context Data the Bot Set (in Step 2):
Step 7 — Debugging the bot
Details on debugging the bot can be found in the previous article.