--- 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 --- # Using Virtual Agent API # Using Virtual Agent API {#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 Using Virtual Agent API The ServiceNow® Virtual Agent API app enables integration of any chat interface or bot with ServiceNow® Virtual Agent or Agent Chat. Available from the ServiceNow Store, this REST API supports two primary use cases: Show full answer Show less * **Standalone bot:** Integrate Virtual Agent as an independent bot with enterprise or third-party chat interfaces that support conversational interactions, allowing end users to engage through multiple channels. * **Secondary bot:** Use Virtual Agent as a specialized secondary bot within a multi-bot environment managed by a primary bot (e.g., IBM Watson Assistant, Microsoft LUIS), handling specific user requests like service tickets. Additionally, the Virtual Agent Bot Interconnect can serve as the primary bot to unify diverse chat channels and enterprise task access. This API is optimized for server-to-server integrations. For complex UI control transformations, consider the Custom Chat Integration Framework. ## How It Works User input flows from a third-party chat or primary bot to the Virtual Agent API via an inbound REST POST request. The ServiceNow AI Platform authenticates and processes this input, routing it to Virtual Agent or a live agent. The response is then sent back through an outbound REST POST response to the bot or chat interface, which displays it to the user. ## Key Features * Support for many Virtual Agent and Agent Chat features, including rich controls and notifications (varies by API version and ServiceNow release). * Version 3.0.x adds capabilities such as file uploads from private URLs and enhanced synchronous handshakes. * Supports bot-to-bot integration scenarios with multiple bots communicating via a primary bot. * Automatic closure of idle bot-to-bot conversations after one hour of inactivity. * Configurable multiple provider applications for environments with multiple primary bots. * Transformations of API requests and responses via scripted extensions. * Enables Now Assist experience to support generative AI skills across multiple channels. ## Limitations The API does not support chat branding through this integration. ## Version Compatibility and Licensing The Virtual Agent API app is compatible with ServiceNow releases from Paris through Yokohama, with feature support varying by version. It requires a Pro license similar to Virtual Agent. ## Installation and Configuration * Install the Virtual Agent API app from the ServiceNow Store. * Review and configure the inbound REST endpoint and authentication (Message Authentication with Static or Hash tokens is recommended over Basic or OAuth). * Set up the outbound REST endpoint and authentication to receive Virtual Agent responses. * Configure provider applications when supporting multiple primary bots and AI agents. ## Practical Benefits for ServiceNow Customers By using the Virtual Agent API, ServiceNow customers can extend Virtual Agent capabilities beyond the native ServiceNow interface, integrating conversational AI into existing enterprise chat platforms or custom bots. This enables a unified, scalable, and flexible conversational experience across multiple channels and bot ecosystems, improving end-user engagement and operational efficiency. Use the ServiceNow® Virtual Agent API app to integrate any chat interface or a bot with ServiceNow® Virtual Agent or Agent Chat. The app is available from the ServiceNow® Store. ## Overview of the Virtual Agent API {#virtual-agent-api__section_cxx_ldc_qmb} The Virtual Agent API is a REST API. This API is built on the conversational custom chat integration framework that is provided with Virtual Agent starting in the Paris release. The API enables ServiceNow developers, advanced users, and admins to use Virtual Agent in either of the following ways: Standalone bot : Use Virtual Agent as a standalone bot that you integrate with enterprise or with any other third-party chat interface that supports conversational interfaces. Your end users can interact with the Virtual Agent and Agent Chat through multiple channels by using this integration. Secondary bot : Use Virtual Agent as a secondary bot in an environment that has multiple, specialized bots managed by a primary bot. In this scenario, a primary bot manages communication with secondary bots on behalf of the end user. A primary bot could be IBM Watson Assistant, Microsoft LUIS, or a homegrown primary bot. Your secondary bots, such as the ServiceNow bot, might handle specific types of end-user requests, such as service tickets or reservations. Bot Interconnect : Use Virtual Agent Bot Interconnect as the primary bot in a diverse chat environment. Bot Interconnect creates a unified chat experience and gives your end users access to multiple channels and a wide variety of enterprise tasks that are available from ServiceNow. The Virtual Agent API is useful for creating server-to-server integrations. However, for integrations that require the transformation of unsupported controls that must be rendered in your existing chat interface, consider using the [Custom Chat Integration Framework](https://servicenow-prod.fluidtopics.net/FpLRa3ECTiRNPyEvSvT3ZQ "Conversational custom chat integration framework is a powerful framework consisting of scriptable APIs and configurations to bring the ServiceNow Virtual Agent to any conversational interface."). For information about features such as the URL format and the supported request and response parameters in the Virtual Agent API, see Virtual Agent Bot Integration API. ![Video link to Virtual Agent Academy.]() [Augment your experiences with the Virtual Agent API](https://www.youtube.com/watch?v=cyhmMyG4jKk) (Virtual Agent Academy video) ## How the Virtual Agent API works {#virtual-agent-api__section_ivs_d2r_fnb} The following diagram shows how the REST API processes user input from a third-party chat interface or a primary bot, and then generates a bot response. 1. The user provides input to a primary bot or third-party chat interface. 2. The bot sends a POST request JSON to the inbound REST endpoint (via scripted REST API). 3. The ServiceNow AI Platform authenticates and processes the request, which is sent to Virtual Agent or a live agent. 4. The ServiceNow AI Platform sends a POST response JSON from the outbound REST endpoint (via REST API) back to the bot. 5. The primary bot or third-party chat interfaces displays the response to the user. {#virtual-agent-api__ol_pwf_jqc_kyb} Figure 1. Inbound and outbound REST endpoints in the Virtual Agent API To see a demonstration of the Virtual Agent API and an FAQ, see [Getting Started with Virtual Agent APIs](https://community.servicenow.com/community?id=community_article&sys_id=080e3903dbc4e4107d3e02d5ca96198c) on the Community site. ## Limitations {#virtual-agent-api__section_xqy_r1l_2qb} The Virtual Agent API does not support the following features: * Chat branding through this Virtual Agent API integration {#virtual-agent-api__ul_yqy_r1l_2qb} ## Version and release compatibility {#virtual-agent-api__section_t11_5zb_dqb} {#virtual-agent-api__table_syv_gzb_dqb__entry__2} | Version | Compatible Releases | |-|-| | 3.14.3 | Yokohama | | 3.14.2 | Xanadu | | 3.14.1 | Xanadu | | 3.10.0 | Washington DC | | 3.9.x | Vancouver | | 3.8.x | Vancouver | | 3.7.x | Utah | | 3.5.x | Tokyo | | 3.0.x | San Diego | | 2.0.x | Rome A subset of features is compatible with Quebec. | | 1.3.0 | Quebec | | 1.0.12 | Quebec | | 1.0.9 | Paris | [Table 1. Virtual Agent API version and release compatibility] {#virtual-agent-api__table_syv_gzb_dqb} Note: The Virtual Agent API requires a Pro license similar to that of Virtual Agent. * **[Virtual Agent API features](https://servicenow-prod.fluidtopics.net/7kND4JfnHfbRsLynJZYMug)** 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. * **[Virtual Agent API features available in Store release 2.0.x](https://servicenow-prod.fluidtopics.net/~X_H2u0xGV9sp_wInHx55g#va-api-features-v2)** Virtual Agent API version 2.0.x provides access to more of the same features that are available in Virtual Agent and Agent Chat, including rich control support and notifications. * **[Virtual Agent API features available in Store release 3.0.x](https://servicenow-prod.fluidtopics.net/2nTXU8_vE2myangzj4PMLg#va-api-features-v3)** Virtual Agent API version 3.0.x provides access to more of the same features that are available in Virtual Agent and Agent Chat, including the ability to upload files from a private URL and synchronous handshake enhancements. * **[Install the Virtual Agent API](https://servicenow-prod.fluidtopics.net/d7lxfjlAW1Z5MATPSvt95g)** Install the Virtual Agent API app to integrate any chat interface or a bot with ServiceNow® Virtual Agent or Agent Chat. * **[Review the inbound REST endpoint and configure inbound authentication](https://servicenow-prod.fluidtopics.net/LXMLIToy9sThPC66HyACqw)** After you install the Virtual Agent API, navigate to the Scripted REST API resource to review the endpoint and set up authentication. * **[Configure Message Authentication for inbound communication](https://servicenow-prod.fluidtopics.net/4uduMd1pxLnEtnmDb11afQ)** You can configure Message Authentication for the Virtual Agent API instead of Basic or OAuth. Message Authentication involves configuring either Static or Hash tokens, setting up Provider Authentication, and setting the channel identity. * **[Configure the output response REST endpoint and outbound authentication for the Virtual Agent API](https://servicenow-prod.fluidtopics.net/wQ5xr3VMBS8HLsd4Gzv1RA)** Specify the outbound endpoint URL to which the Virtual Agent responses are posted. Configure outbound authentication. * **[Virtual Agent bot-to-bot integration](https://servicenow-prod.fluidtopics.net/ymeZhpxQ3ZnVFXuhkIYZRg)** The Virtual Agent API supports environments that use multiple bots. In this situation, a primary bot communicates with third-party secondary bots, such as a ServiceNow bot. * **[Closing 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. * **[Configure multiple provider applications](https://servicenow-prod.fluidtopics.net/iLxWnmAximS7G9df6GoKTg)** You can configure multiple provider applications to support AI agents where there are multiple primary bots using Virtual Agent API and you need to distinguish between them. * **[Transform Virtual Agent API request and response](https://servicenow-prod.fluidtopics.net/u1JaKg3Ru45Zdx7WILXCgQ)** You can transform Virtual Agent API request and response into supported formats through the scripted extension points provided in Virtual Agent API. * **[Enable Now Assist experience in Virtual Agent API](https://servicenow-prod.fluidtopics.net/CB8hy9UeprQWJvheHHEN0Q)** Enable Now Assist experience in Virtual Agent API to support generative AI skills across multiple provider channels.