Virtual Agent API features

  • Release version: Xanadu
  • Updated August 1, 2024
  • 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 enables integration of Virtual Agent and Agent Chat functionalities into your own chat environments. It allows ServiceNow customers to leverage key Virtual Agent capabilities such as intent classification, live agent transfer, and user personalization within external or custom chat interfaces. Feature availability depends on your ServiceNow release and the API Store app version.

    Show full answer Show less

    Key Features

    • Provider Authentication: Supports static, hash, and token-based authentication methods to secure API interactions.
    • User Account Linking: Automatically links user IDs to ServiceNow accounts for a personalized chat experience.
    • Live Agent Transfer: Enables transferring conversations from Virtual Agent to a live agent in Agent Chat seamlessly.
    • Intent Classification: Supports bot-to-bot integrations with two strategies:
      • Primary bot detects user intent and triggers corresponding Virtual Agent topics.
      • Primary bot sends user utterances to Virtual Agent to obtain predicted intent with confidence scores.
    • Automatic Conversation Closure (v1.0.12): Idle bot-to-bot conversations abandoned for over an hour are automatically closed by a scheduled job to maintain system health.
    • Conversation State Tracking: Virtual Agent logs conversation end states and reason codes when users or bots terminate chats, enhancing tracking and reporting.
    • End-of-Conversation Notifications: Primary bots receive notifications when conversations end or when they must take control, with configurable retry attempts for intent detection.
    • Intent Handling Enhancements: Shares NLU confidence scores when NLU is enabled and allows end users to jump directly into topics based on primary bot intent matching.
    • Logging Support (v1.3.0): Introduces system property to enable logging for the Virtual Agent API, aiding in troubleshooting and monitoring.

    Practical Implications for ServiceNow Customers

    By implementing the Virtual Agent API, you can create a richer, more integrated chat experience that combines automated Virtual Agent capabilities with live agent support and personalized user interactions. The API’s intent classification and conversation management features streamline communication flow and enhance user satisfaction. Additionally, automated housekeeping of idle conversations and detailed conversation state tracking improve operational efficiency and reporting accuracy. Logging capabilities introduced in recent versions facilitate proactive monitoring and debugging to ensure smooth API operations.

    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).