It is often necessary for Agents to provide visitors with content from the Dynamics 365 CRM during a live chat-engagement. For example, an agent may wish to automatically send a Knowledge Base Article or share important contact details with a visitor. Some of these features may be available in the CRM, but others needs to be customized to suit the business's or agent's requirements.
The Agent-Message Chat API provides a mechanism for CRM Developers to provide code to populate the textfield in Agent Widget with content. This feature is available as of the July '18 Release of Live Assist for Microsoft Dynamics 365.
The Agent-Message Chat API is a client-side javascript library which is automatically bundled into the Agent Chat Widget. It is not necessary to import any web resources to make use of the library.
Accessing the API
The ChatWidget object can be accessed on “window.top.ChatWidget”
The isChatActive() function can be used to check if the Agent's Chat Session is still active.
The getActiveChatId() function returns the current Chat ID.
The getActiveChat() function will return the Chat object that contains two-function:
- sendMessage
- writeMessage
The addEventListener(eventName, handlerFunction) and removeEventListener(eventName, handlerFunction) methods can be used to manage the follow Events:
- "activeChatChanged" - Called when the active chat changes in the Agent Widget.
Send Message Function
This function is used to immediately send a message from the Agent's Widget to a visitor.
It is possible to call this function while the Agent has text waiting to be sent in the corresponding textfield. When the function is called, the new message is sent to the visitor independently, the existing text in the textfield is not affected and can continue to be edited by the agent.
sendMessage: function (message, isPrivate, sendAsHTML, errorCallback); // void response
SendMessage parameters:
- “message” (required): A string with the message to be sent.
- “isPrivate” (default: false): A boolean that indicates if the message is going to be visible to everyone in the chat or just the agent and supervisor(s).
- “sendAsHTML” (default: false): Sends the message as plain text or evaluates and renders HTML (KB: link to article regarding message types)
- “errorCallback” (default: undefined): A callback with an error message in case there’s a failure on the execution of this method.
Write Message Function
This function is used to append or replace the text in the Agent's textfield. The Agent can review and edit the message before sending it as they would do if they had written the message for themselves.
writeMessage: function (message, appendContent, errorCallback);
WriteMessage parameters:
- “message” (required): A string with the message to be sent.
- “appendContent” (default: false): defines if the “message” parameter will replace any content on the agent widget’s textfield or if it will be appended to any preexisting text.
- “errorCallback” (default: undefined): A callback with an error message in case there’s a failure on the execution of this method.
Error Handling
Both “sendMessage” and “writeMessage” functions have an optional callback parameter. During the execution of a call to either function, the errorCallback function fires. The payload, will contain the error message (in string format).
The following are some potential situations might trigger the callback:
- Trying to send a message to a chat that is not active
- Trying to send a message to a chat that does not exist
- Trying to send a message that is too long (more than 1000 characters)
- Trying to send an empty message
Code Examples:
Example 1: send a message
if (window.top.ChatWidget.isChatActive()) {
window.top.ChatWidget.getActiveChat().sendMessage("Hello, how can I help?", false, false);
}
Example 2: send a private message
if (window.top.ChatWidget.isChatActive()) {
window.top.ChatWidget.getActiveChat().sendMessage("Hello, this is a private message visible only by myself and supervisors.", true, false);
}
Example 3: Send a message as HTML
if (window.top.ChatWidget.isChatActive()) {
window.top.ChatWidget.getActiveChat().sendMessage("<span style='font-weight:bold;'>Sending bold text</span>", false, true);
}
Example 4: send a message, handle error message
if (window.top.ChatWidget.isChatActive()) {
window.top.ChatWidget.getActiveChat().sendMessage("Hello, how can I help?", false, false, function(errorMessage){
console.log(errorMessage)
});
}
Example 5: write a message
if (window.top.ChatWidget.isChatActive()) {
window.top.ChatWidget.getActiveChat().writeMessage("Hello, how can I help?", false);
}
Example 5: write a message, appending the text to the content on the chat textfield
if (window.top.ChatWidget.isChatActive()) {
window.top.ChatWidget.getActiveChat().writeMessage("Hello, how can I help?", true);
}