This tutorial describes the functionality of the ServiceNow Livechat connector that allows a handoff from a Cognigy conversational flow to a ServiceNow Bot or to an Agent using the ServiceNow Agent Workspace.
Further, it also explains how to set up the Cognigy.AI Extension and Transformer to support this functionality.
Table of Contents
- Supported Cognigy.AI Versions, Endpoint, & ServiceNow versions
- ServiceNow Tasks
- Using the Extension
This Cognigy.AI Extension and Endpoint Transformer extend the platform to implement the following scenarios
Cognigy Bot to ServiceNow Live Agent Workspace
This allows a user interacting via a Cognigy.AI endpoint (webchat, Azure, etc.) to initiate a handover to a Live Agent using the ServiceNow Agent Workspace. The Cognigy.AI user can initiate the transfer and continue the conversation with a Live Agent. The Live Agent will see a record of all the interactions the user had previously with the Cognigy.AI Bot. The Cognigy.AI user will be identified as a ServiceNow user if their ServiceNow username and email are passed by the extension from Cognigy.AI to ServiceNow. The agent may terminate the conversation at any time and pass control back to the Cognigy.AI Bot. Alternatively, the Cognigy.AI user may terminate by issuing a configurable phrase (such as quit living chat).
Cognigy Bot to ServiceNow Bot
This allows a Cognigy.AI user to initiate a conversation with a ServiceNow Bot via a Cognigy.AI endpoint (webchat, Azure, etc.) and continue a conversation with the ServiceNow Bot. Control of the conversation is handed over to the ServiceNow Bot. The Cognigy.AI user will be identified as a ServiceNow user if their ServiceNow username and email are passed by the extension from Cognigy.AI to ServiceNow. The ServiceNow Bot may terminate the conversation or the Cognigy.AI user may by issuing a configurable phrase (such as quit chat). Once the conversation is started, a Cognigy.AI user may still request a handover to a Live Agent using the appropriate command to the ServiceNow Bot. Only text-based messaging is currently supported. The use of cards or carousels in the ServiceNow Bot is not supported.
In Both scenarios, the extension acts as a pass-through such that the Cognigy.AI Bot is not aware of the conversation occurring with either the ServiceNow Agent or Bot.
Supported Cognigy.AI Versions, Endpoint, and ServiceNow versions
The Extension and Transformer have been developed and tested against Cognigy.AI V4.7. It will be supported in later V4 versions. Any Endpoint that supports the notify function in the transformer is supported.
Please see here for an up-to-date list of supported Endpoints.
This Extension and Transformer have been tested against Quebec release of ServiceNow
You may download and install the Cognigy.AI Extension into your application from the Cognigy.AI Extension library or provided package.
The associated transformer code will need to be manually merged into the Endpoint Transformers functions you are using. This will be easy if you have not modified the existing function but may require some care if you have already implemented your own functionality.
Note the enabled transformer functions.
This Cognigy.AI extension and transformer interact with the ServiceNow platform using the Virtual Agent API. Information about this API, how to install it and configure can be found here.
Once installed you will need to configure the Virtual Agent API Response REST Service Call as detailed here to allow ServiceNow to communicate back to Cognigy.AI.
The configured Cognigy.AI URL will look like this:
This is the notify API call. Details of creating this URL for your application can be found here.
Call Authentication with Cognigy.AI
To allow this call to authenticate against your Cognigy.AI application you will need to modify the Virtual Agent API Response REST Service Call and add a Cognigy API Key.
You can do this in the postMessage screen as shown below:
Note the X-API-Key HTTP header. Its value needs to be an API Key generated in the Cognigy user profile for the account you wish to access Cognigy.AI as. In order to do so:
- Login to Cognigy.AI workbench using this account
- Go to your user profile (top right-hand corner) and on the displayed account page create a new API key
You will also need to create an API Token key in ServiceNow to authenticate incoming calls from Cognigy.AI. This token will be used to configure the extension in Cognigy.AI as detailed below.
Please see section 6 of Review the inbound REST endpoint and configure inbound authentication here.
This enables token-based authentication for incoming REST calls.
If you require your Cognigy.AI end users to be matched against ServiceNow users then you will also need to enable Basic Authentication as described in section 6 above. If you omit this step then users will appear as anonymous even if you configure their username and email address in the Cognigy.AI extension (as detailed below).
This extension and transformer are only configured with basic authentication. ServiceNow also supports OAuth-based authentication for incoming REST calls. You would need to edit the Cognigy.AI extension and transformer code to enable this. This topic is not covered in this document.
Using the Extension
Once installed you will be able to add the extension node type to your application flow in the usual way. A single node type “Start Conversation with ServiceNow” is available in the ServiceNow Livechat category. You should position this node in your flow whenever you wish to initiate a conversation with ServiceNow.
When you edit the properties of the node you will be required to configure the node with the following properties:
ServiceNow (ServiceNow Connection) – Select an existing connection or create a new one.
The connection has the following properties:
- serviceNowInstanceURL – The URL of your ServiceNow instance e.g. https://dev12345.service-now.com.
- serviceNowAPIToken – An API authentication token as described in “ServiceNow Tasks” above.
- serviceNowUserName – The ServiceNow Account username used to connect as described in “ServiceNow Tasks” above
- serviceNowPassword – The associated password for the serviceNowUserName.
Cognigy Session ID, Cognigy User ID, Cognigy Input ID – These are all available in the “Input” data structure of a running application and there are available tokens in the “AI” field options to provide shortcuts as shown above.
Phrase to quit livechat – An easy to type phrase that will allow the Cognigy.AI user to cancel the conversation and return control to the Cognigy Bot. You should advertise this to the user in some way (perhaps by using a Say Node prior to the handover).
User Identifier, User email address – The identifier (username) and email of the ServiceNow user you wish the Cognigy.AI user to be identified as in ServiceNow. If these are omitted then the user will appear as anonymous in ServiceNow to a Live Agent or Bot.
User's locale – this allows ServiceNow to format output appropriate to where the Cognigy.AI user is located. A full list of supported locales is available in the ServiceNow documentation.
You may store results generated by the extension in the Input or Context data stores of the Cognigy application under the configured context key. Typically, this output will be error messages if the extension fails and will enable debugging the connection to ServiceNow.
The primary mode of this extension is to initiate a conversation with a Live Agent using the ServiceNow Agent Workspace. However, if you wish to allow the Cognigy.AI user to connect to a ServiceNow Bot either as an alternative to a Live Agent or as a precursor to a Live Agent conversation (with the transfer being managed by the ServiceNow Bot) then toggle this control to on.