Virtual Agent API features

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Virtual Agent API features

    The Virtual Agent API allows ServiceNow customers to integrate key Virtual Agent and Agent Chat capabilities into their own chat environments. This API supports various features depending on your ServiceNow release and the API Store app version, enabling enhanced conversational experiences and bot-to-bot integrations.

    Show full answer Show less

    Key Features

    • Provider Authentication: Supports static, hash, and token-based authentication for secure integrations.
    • User ID Auto-Linking: Automatically links chat user IDs to ServiceNow accounts to provide personalized interactions.
    • Agent Transfer: Enables seamless transfer from Virtual Agent to a live agent within Agent Chat.
    • Intent Classification: Supports bot-to-bot intent detection via two strategies:
      • The primary bot detects user intent and routes the user to the appropriate Virtual Agent topic.
      • The primary bot sends user input to Virtual Agent to receive intent prediction with confidence scoring, improving topic matching accuracy.
    • Conversation Management:
      • Automatically closes idle conversations after one hour of inactivity using scheduled jobs.
      • Records conversation states and reason codes when conversations end, capturing how and why interactions conclude.
      • Notifies the primary bot when conversations end or when it needs to take control, with configurable retry attempts for intent detection.
    • Intent Confidence Sharing: When NLU is enabled, confidence scores for intent matches are shared, allowing end users to jump directly into relevant topics.
    • Logging Support: Starting with version 1.3.0, logging can be enabled via a system property to assist in monitoring and troubleshooting API interactions.

    Key Outcomes

    By leveraging the Virtual Agent API, ServiceNow customers can:

    • Integrate Virtual Agent capabilities seamlessly into their custom chat environments.
    • Enhance user experience through personalized conversations linked to ServiceNow accounts.
    • Improve intent recognition and routing accuracy in multi-bot setups.
    • Maintain better control and visibility over conversation lifecycles with automatic closures and detailed interaction records.
    • Access operational insights through optional logging, supporting effective management and troubleshooting.

    You can use the Virtual Agent API to integrate many of the same features that are available in Virtual Agent and Agent Chat into your chat environment. Feature support varies depending on your ServiceNow release and the Store app version number of the API.

    For information about the request and response templates for Virtual Agent API, as well as examples of common use cases, see Virtual Agent Bot Integration API.

    Key features

    The main features in Virtual Agent API starting with version 1.0.9 include the following:
    • Provider authentication using static, hash, and token-based authentication
    • Auto-linking user IDs to ServiceNow accounts for a personalized experience
    • Virtual Agent transfer to a live agent in Agent Chat
    • Intent classification in bot-to-bot integrations through the following strategies:
      • The primary bot determines the user intent and sends the user request to Virtual Agent so that the corresponding topic is displayed to the user.
      • The primary bot sends the user utterance to Virtual Agent so that it can discover the intent and return a prediction confidence score. A higher confidence score indicates that the predicted topic more accurately matches the user utterance.

    Version 1.0.12 features

    Automatically close idle bot-to-bot conversations
    You can automatically close conversations that have been idle for more than one hour. The Time Out Abandoned B2B Conversations job runs hourly each day and automatically closes idle conversations that requesters have abandoned.
    Conversation states and reason codes in Virtual Agent interaction records
    When a user or primary bot ends a conversation, Virtual Agent records the state and reason codes in the interaction records. For example, an end user can type End to stop the conversation or click the X button to close the chat.
    Notifying when a conversation ends
    The primary bot is notified when Virtual Agent or Agent Chat conversations end. The primary bot is also notified when it must take control of a conversation. Virtual Agent uses the following flags:
    • completed: Sent when the conversation with Virtual Agent or a live agent is finished.
    • takeControl: Sent when the primary bot must take control. This typically occurs when Virtual Agent can't determine the conversation intent after two consecutive attempts (the default value). You can add the va.bot.to.bot.take.control_times system property to change the default number of attempts that Virtual Agent tries to determine the conversation intent.

    For more information, see Virtual Agent Bot Integration API.

    Changes with intents
    • Share the NLU confidence score for an intent match if NLU is enabled in Virtual Agent.
    • Enable end users to jump directly into a topic based on intent matching by the primary bot.

    Version 1.3.0 features

    Starting with version 1.3.0, Virtual Agent API supports logging as a system property (va.bot.to.bot.logging_enabled).