--- 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 available in Store release 2.0.x # Virtual Agent API features available in Store release 2.0.x {#ariaid-title1} Release version: Yokohama Updated January 30, 2025 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 11 minutes to read 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. ## Support for additional rich controls {#va-api-features-v2__section_bcd_4k1_kqb} Virtual Agent API now supports the following rich controls. Boolean controls : Boolean controls return responses as strings (either Yes or No) for easier localization. For more information about topic localization, see [Localizing Virtual Agent conversations](https://servicenow-prod.fluidtopics.net/jxlvhrkNiSMWC1iYlFcJpg "The ServiceNow platform provides several methods for localizing Virtual Agent conversations, depending on your needs. Use the Localization Framework to manage all aspects of the translation process, whether you are using machine translation, a third-party provider, or both."). Virtual Agent API sends the following example JSON for a boolean control: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "7a36412253a13010ff59ddeeff7b12fb", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "Boolean", "group": "DefaultPicker", "required": true, "nluTextEnabled": false, "label": "Sample Response for boolean control", "options": [ { "label": "Yes" }, { "label": "No" } ] } ], "score": 1 } Custom controls : Topics that use custom controls are now supported. For more information about custom controls, see [Customizing Virtual Agent with custom controls](https://servicenow-prod.fluidtopics.net/XbcJcr_1h_HwErkvfHUogQ "Custom controls are components that ServiceNow developers can create for use in Virtual Agent topics or topic blocks. Such controls include sliders or video players. Custom controls complement the controls provided in Virtual Agent Designer."). Table bot response controls : Topics that use table bot response controls are now supported. For more information, see [Table bot response control](https://servicenow-prod.fluidtopics.net/dvGoFAPKgfmWppG35ucz4w "Use the Table bot response control in a Virtual Agent topic to display a bot response as a table."). All records are returned from Virtual Agent API at once. Virtual Agent will wait for a response from the API client to send the next control. Use the paginationBreak property to display records in chunks to the user. For example, if paginationBreak is set to 10, the user will see 10 records at a time. When the client is ready to move to the next control, it should send DONE. Virtual Agent API sends the following example JSON for a table bot response control: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "Yes", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "OutputTable", "group": "DefaultOutputTable", "label": "Sample Table Rich control", "headers": [ "Number", "Short description" ], "data": [ [ "INC0000005", "CPU load high for over 10 minutes" ], [ "INC0000015", "I can't launch my VPN client since the last software update" ], [ "INC0000025", "Need to add more memory to laptop" ], [ "INC0000035", "Reset my password" ], [ "INC0000055", "SAP Sales app is not accessible" ], [ "INC0009005", "Email server is down." ] ], "paginationBreak": 10, "totalSearchResultsCount": 6, "navigationBtnLabel": "Click for more" } ], "score": 1 } HTML bot response controls : Topics that use HTML bot response controls are now supported. For more information, see [HTML bot response control](https://servicenow-prod.fluidtopics.net/B9hHwnPYv99vwDutkjF5nQ "Use the HTML bot response control to display static HTML text in the Virtual Agent bot response."). Virtual Agent API sends the following example JSON for an HTML bot response control: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "Yes", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "OutputHtml", "group": "DefaultOutputHtml", "style": "inline", "height": 100, "width": 100, "value": " Sample Response for Html control ", "imageUrl": null, "imageHeight": 0, "imageWidth": 0, "links": null }, { "uiType": "InputText", "group": "DefaultText", "required": true, "nluTextEnabled": false, "label": "some text", "maskType": "NONE" } ], "score": 1 } Multi-response bot response controls : Topics that use multi-response bot response controls are now supported. For more information, see [Multi-response bot response control](https://servicenow-prod.fluidtopics.net/ydfuX1EQnmMZgYylcxh~oA "Use the Multi-response bot response control in a Virtual Agent topic to sequentially display two or more outputs. Outputs can be text, image, link, or HTML. Users can move from one output to the next through a provided navigation button."). Virtual Agent API sends the following example JSON for a multi-response bot response control: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "Done", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "MultiPartOutput", "group": "DefaultMultiPartOutput", "navigationBtnLabel": "Click for more", "content": { "uiType": "OutputText", "value": "Text response from multiflow control example", "maskType": "NONE" } } ], "score": 1 } Rich text support : Topics that use rich text are now supported. Rich text includes bold or italicized text, hyperlinks, bulleted lists, and emojis. ## Additional Agent Chat features {#va-api-features-v2__section_tbg_mg1_kqb} The Virtual Agent API now supports the following features when transferring to Agent Chat. Pass agent name and avatar : When the primary bot transfers a chat to a live agent, Virtual Agent can send the agent name and avatar to the primary bot. To enable this, activate Agent names and avatars in Agent Chat settings. An example message payload might look like this: { "requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId":"U94CSJLEN", "message":{ "text":"Live Agent support.", "typed":true }, "userId":"U94CSJLEN", "body":[ { "uiType":"OutputText", "group":"DefaultText", "agentInfo":{ "sentFromAgent":true, "agentName":"Beth Anglin", "agentAvatar":"ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" }, "value":"Thank you for contacting support. I am looking into your question now and will be with you shortly." } ], "agentChat":true, "score":1 } For more information, see [Configure Agent Chat](https://servicenow-prod.fluidtopics.net/yaHMbaI7SnY7h~7cFk3YTw "Configure Agent Chat to enable live agents to chat with customers and manage various conversation features for agents and end users. Through Agent Chat, agents interact with end users, create incident or case records, or transfer chats to another agent or queue."). Live agent wait time : When transferring to a live agent, the primary bot can receive the wait time and display this to the user. To enable this, select Wait Time in the Live chat wait status field in Agent Chat settings. The spinnerType value is set to wait_time. If the Live chat wait status is set to None, the spinnerType value is none. Virtual Agent API sends the following example JSON in the body parameter of the payload. { "uiType":"ActionMsg", "actionType":"StartSpinner", "spinnerType":"wait_time", "message":"Routing you to a live agent...", "waitTime":"8 Seconds" } For more information, see [Configure Agent Chat](https://servicenow-prod.fluidtopics.net/yaHMbaI7SnY7h~7cFk3YTw "Configure Agent Chat to enable live agents to chat with customers and manage various conversation features for agents and end users. Through Agent Chat, agents interact with end users, create incident or case records, or transfer chats to another agent or queue."). Send chat history from the primary bot to Virtual Agent : The primary bot can pass chat history to a live agent so that the agent can see the context of the conversation. Virtual Agent converts the message history to HTML and then to an image. * The converted image is sent to the live agent as the first message of the chat. * The primary bot should send the message history in the first request. In any other request after the first request, the message history payload will be ignored. * Only text messages are supported. * The primary bot can pass any URL as a value in the text message, but the live agent can only view it as part of the image. The live agent will not be able to click the link. {#va-api-features-v2__ul_thk_p31_kqb} Example message payload: {​       "value": "Help me with password reset",​       "displayName": "able",​       "type": "text"​       "isBotMessage": false,​     } Note: In the previous example, type is case sensitive and should have a value of text. ## Enriched requests from the primary bot {#va-api-features-v2__section_xcn_f41_kqb} The Virtual Agent API now supports the following requests from the primary bot. System parameters and context variables : The primary bot can pass system parameters and context variables as input, and Virtual Agent will honor these  parameters. System parameters such as liveagent_devicetype, liveagent_requester_session_language, liveagent_topic, topic, live_agent_only, and liveagent_devicetimezone are supported. Custom context variables and Agent Chat context variables are also supported. Example message payload: {​ "requestId": "f42f3550-5b44-4cde-aa52-xxxxxxxxxx",​ "clientSessionId": "xxxxxxxxxx",​ "token": "abcd",​ "message": {​     "text": "Test",​     "typed": true​ },​ "contextVariables": {​        "requester_session_language": "es"​ },​ "userId": ""abel.tuter",​ "emailId": "abel.tuter@example.com"​ }​ For more information, see [Live agent chat context variables](https://servicenow-prod.fluidtopics.net/fpc9jRUoIT_yF__WK0iCRw "Use chat context variables to pass certain information from the topic to share with a live agent or to control how bot conversations are routed to live agents. Virtual Agent includes some default variables, and you can define new ones.") and [Configure context variables for storing chat-related information](https://servicenow-prod.fluidtopics.net/8bAn0UJ~5THSinULZ8opTg "Specify chat context variables, also called Live Agent chat variables, for storing chat-related information, such as pre-chat survey responses. These variables contain contextual information that can be used to determine topic intent or control how chats are routed to live agents. You can also define variables to capture contextual information passed in Virtual Agent topic scripts to share with live agents."). User timezone : Set the user's timezone by passing it in the request payload. Once set, that timezone setting is retained until it is reset. Example message payload: {​     "requestId": "xxxxxx-xxxxxx-xxxx-xxxx-xxxxxxxxxx",​     "clientSessionId": "xxxxxxxx-xxxx",​     "token": "xxxxx",​     "action" : "SET_USER_TIMEZONE",​     "userId": "able.tuter",​     "emailId": "abel.tuter@example.com",​      "timezone":"Asia/Kolkata"​ } When using this functionality, consider the following: * The conversation must be open (current) in order to convert date and time to the user's timezone. * The primary bot must send date and time in one of the following formats: * Timezone name. For example, Asia/Kolkata or America/New_York. * Date Time 24-hour format. For example: YYYY-MM-DD HH:MM:SS {#va-api-features-v2__ul_wjl_qjb_kqb} * The Virtual Agent API uses the timezone specified by the primary bot, even if the timezone it sets differs from the value stored in the \[sys_user\] table. * To set the user timezone, send the SET_TIMEZONE action. If the timezone name is not valid, the timezone value defaults to UTC time. For example, 2021-02-16 20:13:13. {#va-api-features-v2__ul_vjl_qjb_kqb} ## Support for node skipping {#va-api-features-v2__section_b13_zry_3qb} Virtual Agent API supports skipping a node if it is designed to do so in the topic. For example, in Virtual Agent Designer, you can designate a user input control as skippable in the AdvancedHide or skip this node area of the property sheet. Figure 1. Condition or script that allows the user to skip the node For more information about defining a node as skippable, see [Virtual Agent Designer user input controls](https://servicenow-prod.fluidtopics.net/eQGVrD~7FoujIzQs94XCiQ "Use the collection of input controls provided by Virtual Agent Designer to prompt and capture information from the user in a conversation."). If a node is marked as skippable, the bot will present that option to the user. If the user skips it, the primary bot should pass the skip command as depicted in the following example. { "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "835607", "token": "snow", "message": { "text": "_skip_", "typed": false }, "emailId": "beth.anglin@example.com", "userId": "beth.anglin" } ## Synchronous handshake support {#va-api-features-v2__synchronous_support} Note: These requirements apply to version 2.0.x of the Virtual Agent API. For greater synchronous handshake functionality, upgrade to version 3.0.x, which supports live agent transfer and other enhancements. For details, see [Synchronous handshake enhancements](https://servicenow-prod.fluidtopics.net/2nTXU8_vE2myangzj4PMLg#va-api-features-v3__synchronous_support_enhancements). When enabled, Virtual Agent delivers responses to the primary bot synchronously. If you want to enable communication with Virtual Agent in synchronous mode, you must manually turn off the following features in order for the handshake to work: * Agent Chat * Notifications * Typing indicators {#va-api-features-v2__ul_p3g_33j_gqb} Note: Topics that use the following features are not supported in synchronous mode: [file upload](https://servicenow-prod.fluidtopics.net/eQGVrD~7FoujIzQs94XCiQ "Use the collection of input controls provided by Virtual Agent Designer to prompt and capture information from the user in a conversation."), the [Action utility](https://servicenow-prod.fluidtopics.net/wA0L2dM3~Em5QA~xiBtHBQ "Use the Action utility in a Virtual Agent topic to select the flow action properties that the node should create. The Action utility integrates Virtual Agent with the ServiceNow Workflow Studio product."), and the [Pause topic block](https://servicenow-prod.fluidtopics.net/hrDycVOnYJ4p9BKWOgl5pw "Virtual Agent provides pre-built topic blocks that topic authors or admins can use to perform specific platform-related functions or tasks in bot conversations. For example, certain topic blocks enable you to check agent availability or generate AI Search results."). To disable these features and enable synchronous support, follow these steps: 1. Exclude the Bot to Bot channel from Agent Chat. 1. Navigate to All, and then enter sys_properties.list in the filter. 2. Select the com.glide.cs.exclude.liveagent.support system property to open it. 3. Add Bot To Bot to the Value field. Figure 2. Exclude the Bot To Bot channel from Agent Chat 4. Click Update. {#va-api-features-v2__ol_fv2_jr4_kqb} 2. Navigate to All, and then enter sys_cs_channel.list in the navigation filter. 3. Select the Bot to Bot record. 4. Clear the Enable Notifications check box to disable it. 5. Clear the Support typing indicator check box to disable it. 6. Select the Synchronous check box. Figure 3. Bot to Bot channel with synchronous support enabled Note: If the Synchronous field is not visible, you can configure the form layout to show it. 7. Click Update. {#va-api-features-v2__ol_icm_x3j_gqb} ## Notifications support {#va-api-features-v2__section_u3d_gcs_2qb} Use Virtual Agent API to send the following types of notifications in the Bot to Bot channel when it is enabled in asynchronous mode: * Simple: Text-only notifications. Simple notifications are delivered as soon as they arrive. * Image Card: An image that is uploaded to the server or specified with a URL. * Record Card: Specified columns from a record in a table. * Actionable: Provides the user with the opportunity to perform certain actions. Actionable notifications are queued. The user can retrieve them on demand by sending the Show Notification command. {#va-api-features-v2__ul_rrg_2ks_2qb} For more information, see [Configuring Virtual Agent notifications](https://servicenow-prod.fluidtopics.net/G0QPUogxMveNLyzIjncUzA "Send ServiceNow notifications directly to users via the Virtual Agent chatbot on supported messaging channels. Notifications can be simple informational messages for review, or actionable messages with buttons that users can select to perform certain actions."). Virtual Agent API sends the following example JSON for a simple notification: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "Done", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "OutputCard", "group": "DefaultOutputCard", "templateName": "Notification", "data": "{\"sys_id\":null,\"recordDisplayValue\":null,\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":null,\"tableLabel\":null,\"enableLink\":false,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[],\"table_name\":null,\"url\":\"http://192.168.1.9:8080/null.do?sys_id=null\"}" } ], "completed": true, "score": 1 } Virtual Agent API sends the following example JSON for an Image Card notification: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "Done", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "OutputCard", "group": "DefaultOutputCard", "templateName": "Notification", "data": "{\"sys_id\":null,\"recordDisplayValue\":null,\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":\"http://xxxxxx.service-now.com/2b2d0d2653a13010ff59ddeeff7b120d.iix\",\"tableLabel\":null,\"enableLink\":false,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[],\"table_name\":null,\"url\":\"http://192.168.1.9:8080/null.do?sys_id=null\"}" } ], "completed": true, "score": 1 } Virtual Agent API sends the following example JSON for a Record Card notification: { "requestId": "asd2423-wrr434-weruyt-1234567", "clientSessionId": "", "nowSessionId": "", "message": { "text": "Done", "typed": false, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "body": [ { "uiType": "OutputCard", "group": "DefaultOutputCard", "templateName": "Notification", "data": "{\"sys_id\":\"552c48888c033300964f4932b03eb092\",\"recordDisplayValue\":\"INC0010112\",\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":null,\"tableLabel\":\"Incident\",\"enableLink\":true,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[{\"fieldLabel\":\"Number\",\"fieldValue\":\"INC0010112\"},{\"fieldLabel\":\"Short description\",\"fieldValue\":\"Assessment : ATF Assessor\"}],\"table_name\":\"incident\",\"url\":\"http://192.168.1.9:8080/incident.do?sys_id=552c48888c033300964f4932b03eb092\"}" } ], "completed": true, "score": 1 } Notifications for the Bot to Bot channel are disabled by default. To enable them, do the following: 1. Navigate to All, and then enter sys_cs_channel.list in the navigation filter. 2. Open the Bot to Bot record.If prompted, enable editing on the record. 3. Select the Enable Notifications check box. 4. Click Update. {#va-api-features-v2__ol_mx2_5ps_2qb} Admins can limit the number of recipients per notification by modifying the com.glide.cs.per_notification_user_limit property. The default value is 1000. ## Topic switching using the topic name {#va-api-features-v2__section_h3z_v2l_2qb} In addition to using the topic ID or topic intent ID to switch topics, you can use the topic or topic intent name. It is recommended that you only send either the topic ID or the topic name. Currently, if either is incorrect or if the bot is already in the specified topic, Virtual Agent does not send any response. Usage depends on the mode you are using, as follows: * NLU topic discovery: Use the topic intent name or ID. * Keyword topic discovery: Use the topic name or ID. {#va-api-features-v2__ul_j1k_pgl_2qb} The primary bot can send the SWITCH action along with the topic name to switch directly to a  particular  topic. Example message payload:    {​   "requestId": "xxxx-xxxx-xxxx-xxxx",   "clientSessionId": "xxx-xxx-xxx-xxx",   "action":"SWITCH",   "topic":{ ​     "name": "Topic Name"​  },​   "userId": "beth"​ } ## Typing indicator support {#va-api-features-v2__section_mfv_mrd_gqb} You can enable typing indicators for users and live agents. Currently, typing indicators are displayed as follows: * Displayed to the agent when the user is typing * Displayed to the user when the bot is preparing a response {#va-api-features-v2__ul_zld_llb_kqb} When the typing indicator is enabled, Virtual Agent API sends the StartTypingIndicator and EndTypingIndicator  actions in the response payload. For example: {​         "uiType":"ActionMsg",​         "actionType":"StartTypingIndicator"​ } ​ To send the user typing indicator to a live agent, the client should send  the TYPING  action. When the user finishes typing, the  client should  send the  VIEWING  action. For example: {​     "requestId": "xxxxxx-xxxxxx-xxxx-xxxx-xxxxxxxxxx",​     "clientSessionId": "xxxxxxxx-xxxx",​     "action": "TYPING/VIEWING",​     "userId": "able.tuter",​     "emailId": "abel.tuter@example.com",​     "timezone":"Asia/Kolkata"​ }​ To enable typing indicators, follow these steps. 1. Navigate to All, and then enter sys_cs_channel.list in the navigation filter. 2. Select the Bot to Bot record. 3. Select the Support typing indicator check box. 4. Click Update. {#va-api-features-v2__ol_nrn_tsd_gqb} *[\>]: and then