Introduction
Chat activity records are a type of CRM activity that is created when you install Live Assist for Dynamics 365. It is used to hold details about chats for later reference and analysis. Live Assist will automatically create chat activities for chats initially handled by human agents or those handled by bots acting as an agent using the Bot Agent Connector.
Bots using the Bot Escalation SDK must take control of the creation of chat activities. You may want to create chat activities for all chats handled by your bot or only those you eventually escalate to a human agent.
Creation of chat activities is done directly against CRM so you will be using the Dynamics CRM Web API and we provide some guidance below.
Web API
You can programmatically connect to Dynamics for 365 through Microsoft Dynamics 365 web services.
Authentication
In order to make requests against the Dynamics CRM Web API, you will need to be authenticated. Microsoft provides a guide that explains this process.
You can follow this guide in order to get authenticated against the Web API for your Dynamics 365 Organization.
An overview of this process is as follows:
-
Create an application in Azure Active Directory (AAD).
-
Create an application user in your CRM which uses the Application ID of the application created in step 1.
-
If the application and your CRM are in different AADs you will need to add this application to your CRM’s AAD.
-
Assign a relevant role to the application user.
- Use the code at https://github.com/davidyack/Xrm.Tools.CRMWebAPI/tree/master/dotnet to create the Chat Activity. We use this code in our bot code as per https://support.liveassistfor365.com/hc/en-us/articles/360006116494
See the sections below for extra details which you may need.
Adding your application to an AAD
If the application you added is in a different AAD to your CRM, you will need to add this application to the AAD your CRM belongs to.
To do this you will need to construct a URL as follows and visit it:
https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id={CLIENTID}&resource=https%3A%2F%2Fgraph.windows.net
(Where {CLIENTID} is taken from the application you created.
Visit this URL and log in as an administrator for your CRM.
After doing this you will be able to save the application user using the client ID as the application ID. This user will then be able to act as a user in your CRM which you can use for authentication from your bot.
Assigning relevant roles to your Application User
You can only assign custom roles to application users.
You can copy the Live Assist Administrator role and use this. (This will give you all the access you need to create chat activities, although you may want to create your own role and restrict this further).
As an administrator inside your CRM, click on the drop-down on the top menu bar or Settings and then click on Security.
Then select Security Roles
Then select Live Assist Administrator
Select Actions and Copy Role
Give the role a name and click OK.
You can then assign this role to the application user which you have created.
Request Access Tokens
Once you have set up an application and an application user following the above guide you can use the details of these to request access tokens which you will use when making requests to the Web API. Microsoft provides a guide on how to do this using the ADAL library.
Authority
Depending on which method you use for requesting your auth token, you may need to specify an authority.
This should be in the format:
https://login.windows.net/{DIRECTORY_ID}
You can find your directory ID as follows:
Visit https://portal.azure.com and log in (as an administrator) for the account where your Dynamics instance is configured under.
Select Azure Active Directory and Properties. You should then see your Directory ID on the next tab that appears.
Send Requests
See the Microsoft documentation for details of how to make basic requests through the Web API or more conveniently https://github.com/davidyack/Xrm.Tools.CRMWebAPI/tree/master/dotnet
Chat Activity Model
The CRM entity you will need for chat activities is cxlvhlp_chatactivities.
There are a number of fields that you may want to populate (please note that the below list only contains fields relevant for bots to populate - other attributes exist but they are used internally by Live Assist for Dynamics 365 and shouldn’t be set through the API):
cxlvhlp_chatstarttime
(mandatory)
datetime
This attribute holds the time that the chat started. It is in the format yyyy-mm-ddThh:mm:ssZ. e.g. for August 1st 2017 at 10am you would use 2017-08-01T10:00:00Z.
subject
(mandatory)
This attribute holds a short description of what the subject of the chat is.
cxlvhlp_chatendtime
(optional)
This attribute holds the time that the chat ended. It is in the format yyyy-mm-ddThh:mm:ssZ. e.g. for August 1st 2017 at 10am you would use 2017-08-01T10:00:00Z.
statecode
(optional)
numeric
0: open, 1: completed
This attribute holds the status of the chat. If it is not provided it will default to open.
cxlvhlp_ChatOrigin
(optional)
text
"100000000": web
"100000001": mobile
This attribute holds which source the chat came from.
cxlvhlp_SourcePageURL
(optional)
text
This attribute holds the URL of the page which the customer was visiting when the chat started.
cxlvhlp_IsCustomerAuthenticated
(optional)
boolean
This attribute holds if the customer was authenticated or not. (true if they were authenticated, false otherwise)
cxlvhlp_EndReason
(optional)
numeric
This attribute holds the recorded end reason for the chat activity.
Reason Codes:
100000000 : Agent Disconnected
100000001 : Agent Ended Chat
100000002 : Visitor Disconnected
100000003 : Visitor Started a New Chat
100000004 : Visitor Ended Chat
cxlvhlp_botname
(optional)
text
This attribute holds the name of the bot which handled the chat.
cxlvhlp_channel
(optional)
text
This attribute holds the name of the channel which was used for the chat.
cxlvhlp_customer_cxlvhlp_chatactivity_contact@odata.bind
(optional)
text
This attribute holds a reference to the ID of a contact in CRM. e.g. for a customer with contact ID 0ee041e0-b428-4c3b-84b2-0a713ab6771b : /contacts(0ee041e0-b428-4c3b-84b2-0a713ab6771b).
regardingobjectid_contact@odata.bind
(optional)
text
This attribute holds a reference to the ID of a contact in CRM. e.g. for a customer with contact ID 0ee041e0-b428-4c3b-84b2-0a713ab6771b : /contacts(0ee041e0-b428-4c3b-84b2-0a713ab6771b).
Example
POST to the following URL:
https://{CRMURL}/api/data/v8.1/cxlvhlp_chatactivities
with the following headers:
Accept : application/json
Authorization : Bearer {ACCESS_TOKEN}
And the following body:
{
"subject" : "test from API.",
"cxlvhlp_chatstarttime" : "2017-08-01T10:00:00Z",
"cxlvhlp_ChatOrigin" : "100000000",
"cxlvhlp_SourcePageURL" : "https://mytestsite.com/some_test_page",
"cxlvhlp_IsCustomerAuthenticated" : true,
"cxlvhlp_botname" : "Order Bot",
"cxlvhlp_channel" : "Bot channel 1",
"cxlvhlp_customer_cxlvhlp_chatactivity_contact@odata.bind" : "/contacts(0ee041e0-b428-4c3b-84b2-0a713ab6771b)",
"regardingobjectid_contact@odata.bind" : "/contacts(0ee041e0-b428-4c3b-84b2-0a713ab6771b)"
}
Passing created chat activity details in the Context Service
When you successfully create a chat activity in CRM you should receive a 204 response. One of the response headers should be called OData-EntityId and this should be in the format:
https://{CRMURL}/api/data/v8.1/cxlvhlp_chatactivities(3d1e8ef9-307b-499d-a264-8ebca5c3682c)
(Where 3d1e8ef9-307b-499d-a264-8ebca5c3682c is the ID of the newly created chat activity ID.)
You can pass this ID into the context service (as the chatActivityId attribute). If you do this and when the chat is escalated to a human agent, Live Assist for Dynamics 365 will add extra data into this same chat activity and update it as necessary. This gives you a way to consolidate all chat data into a single CRM activity record.
Escalated chat data
When a chat is escalated from a bot to a human agent in Live Assist for Dynamics 365 and the chat activity ID is passed to the context service, the following attributes are set in the chat activity:
cxlvhlp_chatsessionid
This will be set to the ID of the chat in Live Assist for Dynamics 365.
subject
This will be set to “chat with AGENT_NAME SKILL”
cxlvhlp_AgentClientType
This will be set to either web or USD (depending on which client the agent is using).
Associated knowledge article chat activity data
A section exists in the chat activity model which contains details of knowledgebase articles (which are stored in CRM) that bots have referred customers to.
This data contains a link to the article and a value indicating if the customer has read the article or not.
You can program bots to populate this data using the Web API.
Some instructions and sample requests for this are below. Authentication is done the same way as described earlier for the chat activity model.
Populating associated knowledge article data through the Web API
Please note that all the below requests should be made with the following headers:
Accept : application/json
Authorization : Bearer {ACCESS_TOKEN}
Firstly you will need the ID of the article you are referencing. You may know this already or you can find it by making a call to:
https://{CRM_URL}/api/data/v8.1/knowledgearticles
You can then look up the knowledgearticleid value for the article you are referencing.
After you have determined the article ID (we will use e45acedc-91f8-4fd2-83fb-5d7bde158735 for this example), you can add a new record as follows:
POST to: https://{CRM_URL}/api/data/v8.1/cxlvhlp_kbrecordsforbotconversations
With the following body:
{
"cxlvhlp_associatedkbarticle@odata.bind" : "/knowledgearticles(e45acedc-91f8-4fd2-83fb-5d7bde158735)",
"cxlvhlp_readbycustomer" : false
}
If this succeeds, you will see a 204 response with a header:
OData-EntityId : https://{CRM_URL}/api/data/v8.1/cxlvhlp_kbrecordsforbotconversations(e4b9fd03-1d9e-469e-bfff-44ad4d075512)
Now that you have added a record for the particular article, you need to associate it to the chat activity it relates to (for this example we will use the chat activity ID 7f71dea3-eeb5-458a-a75c-e5cc402650b6):
POST to:
https://{CRM_URL}/api/data/v8.1/cxlvhlp_chatactivities(7f71dea3-eeb5-458a-a75c-e5cc402650b6)/cxlvhlp_knowledgearticlessentbybot_relationship/$ref
With the following body:
{
"@odata.id" : "https://{CRM_URL}/api/data/v8.1/cxlvhlp_kbrecordsforbotconversations(e4b9fd03-1d9e-469e-bfff-44ad4d075512)"
}
You should notice that the @odata.id attribute is exactly the OData-EntityId value that you received back from the POST request to cxlvhlp_kbrecordsforbotconversations.