According to the ServiceNow product documentation, The Virtual Agent Bot Integration API allows users to integrate any chat interface or a bot ecosystem with the ServiceNow Virtual Agent and/or Live Agent.

This API is built on the conversational custom chat integration framework provided with Virtual Agent and operates in the sn_va_as_service namespace.

The Virtual Agent API is a REST API that enables ServiceNow developers, advanced users, and admins to use Virtual Agent as a:

  • Standalone ServiceNow bot, integrated with enterprise or any other third-party chat interface that supports conversational interfaces.Your end users can interact with the Virtual Agent and/or Live Agent through multiple channels by leveraging this integration.Or,
  • Secondary bot in a bot ecosystem that has multiple, specialized bots managed by a primary bot.In this scenario, a primary bot (such as IBM Watson Assistant, Microsoft LUIS, or a homegrown primary bot) manages communication with secondary bots, such as the ServiceNow bot, on behalf of the end user. Your secondary bots might handle specific types of end user requests, such as service tickets or reservations.

The Virtual Agent API is useful for creating server-to-server integrations. However, for integrations that require the transformation of rich controls that need to be rendered in your existing chat interface, consider using the Custom Chat Integration Framework.

How the Virtual Agent API Works

The following diagram shows how the REST API processes user input from a third-party chat interface or primary bot and generates a bot response.

Available Integrations In The ServiceNow Store



The Virtual Agent API does not support:

  • Integrations with ServiceNow Virtual Agent as the primary bot
  • Custom controls
  • Notifications delivered through Virtual Agent
  • Chat branding through this Virtual Agent API integration

How To Install the Virtual API

  1. Navigate to System Applications > All Available Applications > All.
  2. Find the Virtual Agent API application using the filter criteria and search bar.You can search for the application by its name or ID. If you cannot find the application, you may have to request it from the ServiceNow Store.Visit the ServiceNow Store website to view all the available apps and for information about submitting requests to the store. For cumulative release notes information for all released apps, see the ServiceNow Store version history release notes.
  3. Click Install.
  4. In the Application installation dialog box, click Install.
  5. See slideshow below

Next: Review Inbound REST endpoint and Configure Inbound Authentication

ServiceNow allows for the following provider authentication methods: Basic, OAuth, Hash, or Static Token.

IMPORTANT NOTE: To support user account linking, you must use Static or Hash token-based authentication. You can use token-based authentication (Static or Hash) with or without Basic or OAuth authentication.

To set up do the following:

  • Set up Basic or OAuth authentication. Ensure that Requires Authentication is selected on the Scripted REST Resource page for Bot Integration.
  • To learn more about OAuth authentication and the possible security configurations for scripted REST APIs, see Enable OAuth with inbound REST
  • Set up message auth, which involves configuring either Static or Hash tokens, setting up Provider Authentication, and setting the channel identity.

Next: Review Outbound REST endpoint and Configure Outbound Authentication Virtual Agent API

Bot to Bot Integration

The Virtual Agent API supports bot ecosystems that have multiple bots, where a primary bot communicates with third-party secondary bots, such as a ServiceNow bot.

There are two types of bot communication with the primary bot:

  • If the primary bot understands an end user’s request (intent) entered in the chat client, the primary bot routes the request to the appropriate secondary bot, which displays the corresponding topic.
  • If the primary bot cannot determine where to route a user request, the primary bot can broadcast a user’s request to all secondary bots. Each secondary bot returns a prediction confidence score for determining the end user’s intent. The primary bot then routes the request to the secondary bot with the highest prediction confidence score.

In both above scenarios, the ServiceNow bot informs the primary bot when the request is completed or when it cannot continue handling the request. The primary bot can then decide whether to inform the end user that the conversation is complete or provide further assistance.

Quick Demo

  • ServiceNow API Demo via YouTube by NOWCommunity

Still Have Questions?

What’s Next?

  • In Part II I will build upon this foundation, walking through the integration process, configuration, and test a Bot to Bot integration using another ServiceNow PDI.
  • If you have a use case you’d like me to test out, let me know.