on - edited on by
Victor Chen
Use the Virtual Agent API to integrate the ServiceNow Virtual Agent into your existing bot ecosystem. The Virtual Agent can be used as a secondary bot to provide answers and content to your existing deployed bot, or as a Primary bot to bring in conversations from a 3rd party bot or another ServiceNow Virtual Agent. As of the Washington release, bot-to-bot integration is also supported with Now Assist in Virtual Agent.
View the Virtual Agent API documentation here. View API request parameter in our API documentation.
Before Getting Started
- Make sure you have a Pro/Enterprise license, which gives you access to the Virtual Agent and the API.
- Make sure your instance is on the Paris release or above.
- Install the Virtual Agent API from the ServiceNow store, for the exact installation steps you can find more details here.
Review the inbound REST endpoint and configure inbound authentication
- Topic discovery can either be performed by the Primary bot or ServiceNow VA. Please refer to key features for more details.
- You can POST either an intent or utterance to the VA REST endpoint.
Configure the output response REST endpoint and outbound authentication for the Virtual Agent API
- Add your endpoint for your primary bot on VA outbound REST message.
- Ensure your API authentication is configured correctly.
- Because VA Bot is async, the instance will POST the JSON back to your endpoint to parse.
- Review the response payload in our VA API doc.
Use Case 1: NLU In Secondary Bot
- A Primary Bot can send the user's utterance to all of the Secondary Bots in its ecosystem, and based on the boolean score returned back by secondary bots, it decides where to route subsequent requests. The boolean NLU score of 1 or 0 is returned by ServiceNow VA, where a score of 1 indicates an intent match and a score of 0 indicates no intent match.
- The Primary Bot will be intelligent enough to route utterances to the ServiceNow VA until the ServiceNow VA asks the Primary Bot to take control back. ServiceNow Virtual Agent will send a "takeControl" flag back to the Primary Bot in case it runs into consecutive failures with same utterance. The default value for this is 2.
- ServiceNow VA will also allow the Primary Bot to interact with agents via Agent Chat.
Use Case 2: NLU In Primary Bot
- The Primary bot has the same NLU engine for all secondary bots to decide which secondary bot to route the request. Depending on the Primary Bot NLU decision, should the Primary Bot decide that ServiceNow Virtual Agent should handle these requests, it will route the conversation to ServiceNow Virtual Agent.
- The Primary Bot will be intelligent enough to route utterances to ServiceNow VA until ServiceNow VA sends back the message for the Primary Bot to take control back. ServiceNow Virtual Agent will send a "takecontrol" flag back to the Primary Bot in case it runs into consecutive failures with same utterance.
- ServiceNow VA will also allow the Primary Bot to interact with agents via Agent Chat.
Example using Google Dialogflow as a Primary Bot, and ServiceNow Virtual Agent as a Secondary bot with a Slack interface
Demo
Implementation KB for Microsoft Azure bot-to-bot: https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB1436882
Implementation FAQs
Q: Can ServiceNow serve as the primary bot?
A: Yes, this feature is enabled out-of-the box for Azure bot, Google Dialogflow, or another ServiceNow VA bot. Find out more in our documentation - Bot Interconnect. For other bots, more custom development is required for integrations. As of the Utah release, Bot Interconnect is a separate store app that can be found in the ServiceNow Store.
- Documentation for Microsoft Power VA bot as secondary bot (Azure account required, Visual Studio Code recommended)
- Documentation for Google Dialogflow as secondary bot (Google Cloud account required)
Q: How would the user authenticate to the Virtual Agent?
A: ServiceNow VA authenticates the provider. You can use the standard platform-supported authentication methods - most commonly Basic and OAuth. You will be able to set them up in REST resource that will become available in your instance once you install the Virtual Agent API Store App. Additionally, we also support JWT, Hash, and Static token-based authentication methods as described in our documentation. The Store App is needed to be able to set these up.
If the provider authentication is successful, we can link the user ID to their ServiceNow profile. In order for this auto-linking to happen, you will pass the user's email ID in request JSON. The account linking only works if you use one of the following token-based authentication methods - JWT, Hash, or Static. Also, the account linking only works with the email ID currently which is mapped against their ServiceNow profile email ID for a match.
Q: What is the difference between the Conversational Custom Chat Integrations option and the Virtual Agent API?
A: Conversational Custom Chat Integration Framework (CCCIF) is a framework that can be leveraged to bring ServiceNow Virtual Agent/Live Agent to any conversational interface or channel. You would use CCCIF for a chat client to VA server integration where customers need to transform our default rich controls into a format that can be rendered on the channel or interface they are integrating with (e.g. WebEx, BlueJeans, G-talk, etc.) This is a high-development effort and used when the other system has its own API request/response, so it requires transformations written using CCCIF. Note: using CCCIF also consumes IntegrationHub transactions.
Virtual Agent API is an integration built on top of CCCIF. Virtual Agent API provides a REST-based Server-to-Server integration. One of the primary use cases Virtual Agent API supports is bot-to-bot integration where customers already have a bot in production but want to augment its capabilities by integrating with ServiceNow's VA in the background while causing no disruption to the end user experience.
Q: Help, I'm unable to generate a response from the ServiceNow Virtual Agent?
A: First, check if adding the 'public' role to the Virtual Agent topic and try again. If that works, then check the auth configuration:
1) Message_Auth is configured on sys_cs_provider_application record. Documentation
2) You are passing a valid emailId in the request body. Request body parameters documentation
Q: How to generate the requestID in the JSON?
A: It is just a unique ID to help you identify the request you send to ServiceNow's Virtual Agent. It can be any alphanumeric character depending on your system or requirements.
Q: How to get the nowBotID in the JSON?
A: This is no longer used. Use the appInboundID in the response body to distinguish between multiple ServiceNow bots if you have them.
Q: Where to read the clientSessionID in the JSON?
A: This is an ID to help you keep track of the conversation that is taking place. This is how you identify that a given set of request and responses tie to an ongoing conversation with the user. The ID format and length depends on your system.
Q: How is NLU confidence returned for intent matches and non-matches across the bot-to-bot ecosystem?
A: In the Paris release, we will not be sending over the individual intent confidence scores (ie. 87%) but rather a boolean confidence match (0 or 1) that hits over the NLU model's CI threshold value for intent discovery match. System property va.bot.to.bot.score.normalization_factor can be utilized to dial up or down the individual intent confidence score to be on par with other bot intent matches. Our default is 1.
We will not be sending the confidence match as 0 if no intent match is found, which then invokes the Fallback topic and a match score of 0. To summarize, if NLU comes back with a Fallback, we will render it a score of 0.
Q: Can I connect with a 3rd party live agent system (VA as the primary bot)?
A: Not at this time.
Q: I’m running to cross-scope privileges error when installing the Virtual Agent API. How do I resolve this?
A: Navigate to System Applications > Application Cross-Scope Access. Filter by Source Scope = “Virtual Agent API”. Ensure that the Status field shows “Allowed” for all records.
Q: What is the format in which the date time picker response has to be provided to the Virtual Agent?
A: We accept date time in milliseconds format. Here is an example:
Q: We want to integrate with a bot that's not listed as supported out-of-box. What are our options?
A: The Virtual Agent API is available to use for any bot ecosystem, however custom implementation is required. It is recommended to consult Expert Services, an implementation partner, or a technical resource who is familiar with bot architecture and using APIs.
For more details please watch the Virtual Agent Academy recorded session on this topic: Augment your bot with ServiceNow workflows with the Virtual Agent API
Hello, I'm using this api in a particular instance... and basically all interactions are as GUEST. How to fix this problem.. are all the settings correct according to the document? Is this due to the implementation of the auth message?
