---
sourceDocument: Yokohama Conversational Interfaces
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/yokohama/conversational-interfaces

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama Conversational Interfaces

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# Virtual Agent API features

# Virtual Agent API features {#ariaid-title1}

Release version: Yokohama  
Updated January 30, 2025  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read
Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 {#va-api-features__section_yps_1fc_qmb}

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.
  {#va-api-features__ul_n2c_nfc_qmb}
{#va-api-features__ul_y2x_cfc_qmb}

## Version 1.0.12 features {#va-api-features__section_fxf_22h_kqb}

[Automatically close idle bot-to-bot
conversations](https://servicenow-prod.fluidtopics.net/UhYRVbBZFynFVKGlyGV_hw "In bot-to-bot integrations (Virtual Agent API), abandoned conversations that are \"idle\" for more than an hour are automatically closed by the scheduled job, Time Out Abandoned B2B Conversations. This job runs hourly each day.")
:   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](https://servicenow-prod.fluidtopics.net/ZuuRpg0W0qr6qLZSr9CEqA "Each time a Virtual Agent conversation occurs, an interaction record captures the entire conversation in the Interactions [interaction] table. The record includes all topic elements used in the conversation, as well as live agent transfers.")
:   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.

    {#va-api-features__ul_dqs_51h_kqb}

    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.
    {#va-api-features__ul_gbx_mz3_kqb}

## Version 1.3.0 features {#va-api-features__section_aj4_22h_kqb}

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