---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference
Release :
- yokohama
ft:locale :
- en-US
ft:publication_title :
- Yokohama API Reference
ft:clusterId :
- crapiref
bundleId :
- crapiref
workflow :
- Creator
---
# Virtual Agent Bot Integration API
# Virtual Agent Bot Integration API {#ariaid-title1}
* Release version: Yokohama
*
* Updated January 30, 2025
*
*  26 minutes to read
The Virtual Agent Bot Integration API provides endpoints that allow
users to integrate any chat interface or a bot ecosystem with the ServiceNow
Virtual Agent and/or Live Agent.
This API is built on the conversational custom chat integration framework provided with Virtual Agent and operates in the `sn_va_as_service` namespace.
For additional information on installing and configuring the Virtual Agent Bot
Integration API, see [Virtual Agent API](https://www.servicenow.com/docs/access?context=virtual-agent-api&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US).
## VA Bot Integration - POST /sn_va_as_service/bot/integration {#ariaid-title2}
Sends a specified message, attachment, or URL to a specified secondary ServiceNow
Virtual Agent (VA) bot.
A customer's site can have one or more secondary ServiceNow bots. In
addition to passing messages to a ServiceNow VA secondary bot, the
primary bot or chat client can use this endpoint to pass messages to an agent through Live Agent chat. Use the action parameter passed in the
request body to specify how the specified content should be handled.
Note:
This endpoint can be either synchronous or asynchronous depending on how it's configured. If asynchronous, when the request is received by the endpoint, it validates the request and responds with a call status of success or failure and the appropriate HTTP status code. The VA then processes the request and sends a second response to the configured response endpoint. For example, for a bot-to-bot integration, the second response would be to the URL of your primary bot. Both of these responses are defined below. For additional information on this configured response endpoint, see [Configure the output response REST endpoint and outbound authentication for the Virtual Agent API](https://www.servicenow.com/docs/access?context=configure-response-endpoint-va-api&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US).
Note:
The responses in the code examples for this endpoint show what is sent from the VA to the configured response endpoint. They don't show the actual response to this endpoint which is a simple success or failure response.
### URL format
Default URL:
/api/sn_va_as_service/bot/integration
### Supported request parameters
{#bot-POST-integration__entry__2}
| Name | Description |
|-|-|
| None | |
[Table 1. Path parameters]
{#bot-POST-integration__entry__6}
| Name | Description |
|-|-|
| None | |
[Table 2. Query parameters]
{#bot-POST-integration__entry__10}
| Name | Description |
|-|-|
| action | Action that the VA should take. Valid values: * AGENT: Switches the conversation from VA to Live Agent. * END_CONVERSATION: Ends the chat conversation. The message.text parameter should be empty when using this action. * START_CONVERSATION: Starts a chat conversation. * SWITCH: Switch the conversation to a topic that matches what is specified in the intent.id or topic.name parameters. Note: Only use the `SWITCH` action for topic switching when the intent discovery happens in the primary bot. If the intent discovery happens in the ServiceNow® VA, use the message.text parameter. * SET_USER_TIMEZONE: Sets the user's time zone to the time zone specified in the timezone parameter. This time zone remains in effect until you reset it using this same parameter. * TYPING/VIEWING: Displays the typing indicator in Live Agent. First send `TYPING` and then after the user finishes typing, send `VIEWING`. * Null or parameter not passed: Sends the message to the ServiceNow VA. {#bot-POST-integration__ul_dtc_3fg_4mb} Data type: String Default: Null |
| botToBot | Flag that indicates whether the conversation is between bots, such as between a primary bot and secondary bot. Possible values: * true: Bot-to-bot conversation. * false: Standalone ServiceNow bot conversation. {#bot-POST-integration__ul_prw_jkj_qmb} Data type: Boolean Default: true |
| clientSessionId | Unique client session identifier of the application/service that the end user is using to communicate with the ServiceNow bot. This ID helps identify the set of request/responses for a specific user conversation. The format of this parameter is determined by the implementer. Data type: String Default: Null |
| clientVariables | Pass-through JSON-formatted name-value pairs that are sent back in the response. These values aren't processed by the endpoint, but can be used to keep specific customer information attached to the conversation. Data type: Object Default: Null |
| contextVariables | JSON-formatted name-value pairs that provide addition information about the user. Provide this information to customize the conversation experience. For additional information on context variables, see [Define and publish chat context variables](https://www.servicenow.com/docs/access?context=ac-configure-context-variables&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US). For example: "contextVariables": { "requester_session_language": "es", "deviceTimeZone": "America/Los_Angeles" "live_agent_only": "true", "liveagent_deviceType": "test_device_type" "topic": "7c3c819073a3101066c7e9344ef6a7e4" } Data type: Object Default: Null |
| emailId | Required when enabling account linking, otherwise all users are considered guest users. Email address of the chat client end user, the person the bot is interacting with. For additional information on account linking, see [Link your ServiceNow user account to a messaging application for Virtual Agent conversations](https://www.servicenow.com/docs/access?context=link-accounts-with-virtual-agent&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US). Data type: String |
| history | History of the primary bot's conversation with the user, starting with the initial request by the user. Data type: Object "history": { "displayName": "String", "isBotMessage": Boolean, "type": "String", "value": "String" } For example: { "isBotMessage": true, "value": "message 1", "displayName": "Bot", "type": "text" }, { "isBotMessage": false, "value": "message 2", "displayName": "User", "type": "text" } |
| history.displayName | Name of the user to whom the message was sent. If the primary bot, pass Bot. Data type: String |
| history.isBotMessage | Flag that indicates whether the message was sent by the primary bot. Valid values: * true: Message was sent by the primary bot. * false: Message was sent by the user. {#bot-POST-integration__ul_mzy_pgc_lqb} Data type: Boolean |
| history.type | Type of message sent. Valid values: text Data type: String |
| history.value | Content of the information. For example, the message text. Data type: String |
| intent | Describes the intent of the conversation. Provide this information when the action parameter is set to `SWITCH`. Data type: Object "intent": { "id": "String" } |
| intent.id | NLU Intent ID of the system topic to switch the conversation to. The intent.id is resolved based on the language passed in the chat session. If no language is passed when starting a conversation, it obtains the language from the user's session/profile. Data type: String Table: CS Topic Language \[sys_cs_topic_language\] |
| message | Required. Details of the message to send to the ServiceNow bot. Data type: Object "message": { "attachment": {Object}, "clientMessageId": "String", "text": "String", "typed": Boolean } |
| message.attachment | Required if sending attachments. Details of each attachment to send. You can only pass attachments as a URL. A virus scan is triggered on all attachments. There is no restriction on the size of an attachment, however, large files can take significant time to transfer. Data type: Array of Objects "attachment": [ { "clientAttachmentId": "String", "contentType": "String", "fileName": "String", "headers":{Object}, "url": "String" } ] |
| message.attachment.clientAttachmentId | Unique identifier of the attachment to send to the ServiceNow bot. The format of this identifier is determined by the implementer. Data type: String Default: Null |
| message.attachment.contentType | Required if attachment specified. Standard mime type of the attachment. Valid values (not case-sensitive): * application/pdf * application/msword * image/png * image/jpeg * text/plain * video/mpeg {#bot-POST-integration__ul_ktc_xnj_4mb} Data type: String |
| message.attachment.fileName | Required if attachment specified. File name of the attachment. Data type: String |
| message.attachment.headers | Additional information needed if the attachment file is private and protected. Data type: Object "headers":{ "Authorization":"String" } |
| message.attachment.headers.Authorization | Information needed to obtain authorization to access the attachment, such as a user name and password. Data type: String |
| message.attachment.url | Required if attachment specified. URL where the attachment is located. The VA obtains the attachment from this URL, runs a virus scan, and then processes the file. If the attachment isn't a public file, you must pass an message.attachment.header object that contains the authorization information so that the attachment can be accessed. You must also ensure that URL domain is present in the trusted domains filed in sys_cs_provider. Data type: String |
| message.clientMessageId | Unique alphanumeric identifier for the message. The format of this identifier is determined by the implementer. Data type: String Default: Null |
| message.text | Required if attachment parameter isn't specified. Message text. The language of the message should be passed in the contextVariables parameter. Data type: String Maximum length: Unlimited |
| message.typed | Required. Flag that indicates whether the message was typed in or was an option selection (selected). Valid values: * true: Message was typed in by the user. * false: Message was an option selection. Data type: Boolean |
| requestId | Required. Unique alphanumeric identifier for this request. The format of this identifier is determined by the implementer. Data type: String |
| silentMessage | Flag that indicates whether this is a silent message. A silent message is a message that doesn't require a response. Valid values: * true: Silent message, no response message expected. * false: Regular message, response message expected. Note: If a request with `silentMessage = true` is sent, all subsequent bot messages remain suppressed until a request to turn off silent mode is sent by passing `silentMessage = false`. Data type: Boolean Default: false |
| timestamp | Unix epoch time when the message was sent from the end user of the chat client. Data type: Number Unit: Milliseconds Default: Current time |
| timezone | GMT time zone of the end user of the chat client. For example: "timezone":"Asia/Kolkata" For a list of the available time zone values, see . Data type: String Default: GMT time zone of the ServiceNow instance. |
| topic | Required if the user wants to switch to a particular topic by specifying a topic name. Name-value pair of the topic to switch to. You can either specify the topic name or the topic sys_id. Note: You can only specify a single topic name or id in the object. Data type: Object "topic": { "name": "String", "id": "String" } For example: { "requestId": "xxxx-xxxx-xxxx-xxxx", "clientSessionId": "xxx-xxx-xxx-xxx", "action":"SWITCH", "topic":{ "name": "Topic Name" }, "userId": "beth" } |
| topic.name | Name of the topic to switch to. Data type: String Table: In the name field of the Virtual Agent topics \[sys_cs_topic\] table. |
| topic.id | Sys_id of the topic to switch to. Data type: String Table: Virtual Agent topics \[sys_cs_topic\] |
| userId | Required. Unique user identifier. This is the identifier of the end user who is interacting with the bot. Data type: String |
[Table 3. Request body parameters]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#bot-POST-integration__entry__76}{#bot-POST-integration__accept-JSON-only-entry-RESTAPI}{#bot-POST-integration__content_type-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
| token | Required if using token-based authentication; optional for Basic or OAuth authentication. Authentication token to use if token authentication has been set up for this endpoint. Data type: String |
[Table 4. Request headers]
{#bot-POST-integration__entry__84}
| Header | Description |
|-|-|
| None | |
[Table 5. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#bot-POST-integration__entry__88}{#bot-POST-integration__entry-400-status-code}{#bot-POST-integration__entry-401-status-code}{#bot-POST-integration__entry-405-status-code}{#bot-POST-integration__entry-500-status-code}
| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. If you receive a 200 status code, but don't receive a response back, check the following things: * Whether the request is failing in Static, JWT, or Hash Based Token validation, which generally happens in the worker thread of Virtual Agent. * Whether the request body format is correct. If incorrect, the conversion doesn't happen correctly. * Whether the request body is missing some required parameters. You can trace exceptions and errors in the System Logs on the ServiceNow instance. * Whether the site defined in the REST Message to receive the response is operational; able to detect in logs. * Ensure the REST Message that defines where to post the response is set correctly. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 405 | Invalid method. The functionality is disabled. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]
### Response body parameters
Status of the endpoint call. This is sent in response when the initial call request is received. The request hasn't yet been processed.
{#bot-POST-integration__entry__100}
| Name | Description |
|-|-|
| error | Description of the detected error. Only returned if an error occurs. Data type: Object "error": { "detail": "String", "message": "String" } |
| error.detail | Details about the encountered error. Data type: String |
| error.message | Error message thrown. Data type: String |
| status | Status of the endpoint call. Valid values: * failure * success {#bot-POST-integration__ul_mdj_f2f_1nb} Data type: String |
[ ]
### VA response body parameters {#bot-POST-integration__section_vb2_yny_jlb}
Response body sent from the VA to the configured response endpoint.
{#bot-POST-integration__table_bql_jkx_zmb__entry__2}
| Name | Description |
|-|-|
| agentChat | Flag that indicates whether the conversation is connected to the ServiceNow Live Agent. Possible values: * true: Chat messages are coming from a live agent. * false: Chat messages are coming from a bot and this parameter isn't returned in the response. {#bot-POST-integration__ul_cql_jkx_zmb} Data type: Boolean |
| body | List of objects that describe the elements of the response message body. Data type: Array of Objects "body": [ { "actionType": "String", "agentInfo": {Object}, "data": "String", "group": "String", "header": "String", "height": Number, "itemType": "String", "label": "String", "maskType": "String", "maxCount": Number, "maxSize": Number, "message": "String", "multiSelect": Boolean, "nluTextEnabled": Boolean, "options": {Object}, "promptMsg": "String", "required": Boolean, "style": "String", "templateName": "String", "type": "String", "uiType": "String", "value": "String/{Object}", "width": Number } ] |
| body.actionType | Type of action message dispatched by the secondary bot to the primary bot. For example, typing indicator or agent wait time. Possible values: * EndTypingIndicator * StartSpinner * StartTypingIndicator {#bot-POST-integration__ul_dgw_fhy_lqb} For example: Sending `StartTypeIndicator` to the primary bot when the typing indicator is enabled. "body": { "uiType":"ActionMsg", "actionType":"StartTypingIndicator" } Sending `StartSpinner` when transferring to Live Agent to display the wait time to the end user. "body": { "uiType":"ActionMsg", "actionType":"StartSpinner", "spinnerType":"wait_time", "message":"Routing you to a live agent...", "waitTime":"8 Seconds" } Data type: String |
| body.agentInfo | If enabled in the agent chat setup, the name and avatar of the associated agent. Data type: Object "agentInfo":{ "agentAvatar":"String", "agentName": "String", "sentFromAgent": Boolean } For example: "agentInfo":{ "sentFromAgent": true, "agentName":"Beth Anglin", "agentAvatar":"https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" } |
| body.agentInfo.agentAvatar | URL of the agent's associated avatar file. For example: "https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" Data type: String |
| body.agentInfo.agentName | Display name of the agent. Data type: String |
| body.agentInfo.sentFromAgent | Flag that indicates whether the message was sent by a live agent. Possible values: * true: Sent by a live agent. * false: Sent by a virtual agent. {#bot-POST-integration__ul_arr_gky_lqb} Data type: Boolean |
| body.data | JSON string that defines the data within the card. Data type: String |
| body.group | Rich control group to which the body element belongs. You can further transform these default controls by writing outbound transformation scripts. For additional information on these scripts, see [Virtual Agent action scripts](https://www.servicenow.com/docs/access?context=va-action-scripts&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US). Possible values: * DefaultOutputCard * DefaultDate * DefaultGroupedPartsOutputControl * DefaultHtml * DefaultOutputImage * DefaultOutputLink * DefaultText * DefaultPicker Data type: String |
| body.header | Link header. Data type: String |
| body.height | Height of the HTML element. Data type: Number Unit: Pixels |
| body.itemType | Type of body element. Possible values: (case-sensitive) * DefaultText * File * Image * Inputtext * outputtext {#bot-POST-integration__ul_fql_jkx_zmb} * DefaultPicker * Picture: Items appear in a carousel. * List: Items appear in a dropdown-style list. {#bot-POST-integration__ul_gql_jkx_zmb} {#bot-POST-integration__ul_eql_jkx_zmb} Data type: String |
| body.label | Label to display for the associated element. Data type: String |
| body.maskType | Sensitivity of the associated data. Possible values: * NONE: Associated data is of a general nature and doesn't need to be secured. * SECURE: Associated data is of a sensitive nature and should be handled securely. {#bot-POST-integration__ul_hbb_dbz_n4b} Data type: String |
| body.maxCount | Only returned when uiType is `FileUpload`. Maximum number of attachments that can be uploaded at one time. Data type: Number (Integer) |
| body.maxSize | Only returned when uiType is `FileUpload`. Maximum size of the attachment that can be uploaded. Data type: Number (Integer) Unit: Megabytes |
| body.message | Only returned when actionType is `StartSpinner`. Message to display to user. Data type: String |
| body.multiSelect | Flag that indicates whether the user can select multiple options. Possible values: * true: Multiple selections. * false: Single selection. {#bot-POST-integration__ul_hql_jkx_zmb} Data type: Boolean |
| body.nluTextEnabled | Flag that indicates whether the user chat client can receive Natural Language Understanding (NLU) text messages. Possible values: * true: Can receive NLU messages. * false: Can't receive NLU messages. {#bot-POST-integration__ul_iql_jkx_zmb} Data type: Boolean |
| body.options | List that describes the options available for a picker control. Data type: Array of Objects "options": [ { "attachment": "String", "description": "String", "enabled": Boolean, "label": "String", "renderStyle": "String", "value": "String" } ] |
| body.options.attachment | URL of the image in the carousel to retrieve. Data type: String |
| body.options.description | Description of the carousel item. Data type: String |
| body.options.enabled | Flag that indicates whether the picker control is enabled on the end user's chat client. In bot-to-bot implementations, the primary bot is responsible for ensuring the picker control is disabled. Possible values: * true: Enabled * false: Disabled {#bot-POST-integration__ul_jql_jkx_zmb} Data type: Boolean |
| body.options.label | Label to display for the associated body.options.value parameter. Data type: String |
| body.options.renderStyle | Style to use when rendering the associated element. Possible value: data Data type: String |
| body.options.value | Value to display for the associated body.options.label parameter. Data type: String |
| body.promptMsg | Prompt message to display with the picker control. Data type: String |
| body.required | Flag that indicates whether the end user must respond to the query in the body element. Possible values: * true: Required * false: Optional {#bot-POST-integration__ul_lql_jkx_zmb} Data type: Boolean |
| body.spinnerType | Only returned when actionType is `StartSpinner`. Type of spinner shown to chat user. Possible values: wait_time: Message indicating the amount of delay before being transferred to a live agent. Data type: String |
| body.style | Style of body element. Possible values: * button * carousel * list * null Data type: String |
| body.templateName | Name of the template to use to display the associated card. Data type: String |
| body.type | Only returned for DefaultOutputLink. Type of return data. Possible values: link Data type: String |
| body.uiType | Type of body element. The possible values depend on the value in the body.group parameter. These values map back to the controls defined in the Virtual Agent Designer. For more information, see [Getting started with Virtual Agent Designer](https://www.servicenow.com/docs/access?context=conversation-designer-virtual-agent&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US). Possible values: * ActionMsg * DefaultOutputCardOutputCard * DefaultDate * Date * DateTime * Time {#bot-POST-integration__ul_qql_jkx_zmb} * DefaultGroupedPartsOutputControlGroupedPartsOutputControl * DefaultHtmlOutputHtml * DefaultOutputImageOutputImage * DefaultOutputLinkOutputLink * DefaultText * InputText * OutputText * FileUpload {#bot-POST-integration__ul_uql_jkx_zmb} * DefaultPicker * Picker * TopicPickerControl * Boolean {#bot-POST-integration__ul_vql_jkx_zmb} Data type: String |
| body.value | Data to use to process the body element. The type of information that is passed back depends on the type of body element. OutputLink: Object. "value": { "action": "String" } OutputImage: String. Image URL. OutputHtml: String. HTML that the client needs to render. Data type: String or Object |
| body.value.action | Only returned for DefaultOutputLink. URL of returned link. Data type: String |
| body.waitTime | Amount of time that the user has to wait before being connected to a live agent. Data type: String |
| body.width | Width of the associated HTML element. Data type: Number Unit: Pixels |
| clientSessionId | Unique client session identifier of the chat application/service that the end user is using to communicate with the ServiceNow bot. Data type: String |
| clientVariables | JSON-formatted name-value pairs that are copied from what is passed in the clientVariables parameter in the request body. These values aren't processed by the endpoint, but can be used to keep specific customer information attached to the conversation. Data type: Object |
| completed | Flag that indicates whether the ServiceNow Virtual Agent has successfully completed the conversation. Possible values: * true: Conversation has been successfully completed. * false: Conversation isn't complete and this parameter isn't returned in the response. Data type: Boolean |
| enterpriseId | Currently unused. |
| message | Details of the message sent to the ServiceNow VA. This is the same as the passed in message object. Data type: Object "message": { "attachment": {Object}, "clientMessageId": "String", "text": "String", "typed": Boolean } |
| message.attachment | Details of the attachment. Attachments can be either a file or a URL. Data type: Object "attachment": { "clientAttachmentId": "String", "contentType": "String", "fileName": "String", "url": "String" |
| message.attachment.clientAttachmentId | Unique identifier of the attachment sent to the ServiceNow VA. The format of this identifier is determined by the implementer. Data type: String |
| message.attachment.contentType | Standard mime type of the attachment. Possible values (not case-sensitive): * application/msword * application/pdf * image/jpeg * image/png * text/plain * video/mpeg {#bot-POST-integration__ul_xql_jkx_zmb} Data type: String |
| message.attachment.fileName | File name of the attachment. Data type: String |
| message.attachment.url | URL where the attachment is located. Data type: String |
| message.clientMessageId | Unique alphanumeric identifier for the message. Data type: String |
| message.text | Message text. Data type: String Maximum length: Unlimited |
| message.typed | Flag that indicates whether the message was typed in or was an option selection (selected). Possible values: * true: Message was typed in by the user. * false: Message was an option selection. Data type: Boolean |
| nowBotId | Currently unused. |
| nowSessionId | Currently unused. |
| requestId | Unique identifier for this request. Data type: String |
| score | Intent confidence score from the ServiceNow NLU model, specified as a percent, such as 87.3%. This score enables the primary bot to make the decision whether to surface the associated intent based on the primary bot's NLU model's confidence threshold. The ServiceNow NLU model's confidence threshold is ignored on the ServiceNow instance so that the primary bot's NLU model's confidence threshold can be consistently applied across all secondary bots. Data type: Number |
| takeControl | Flag that indicates that the ServiceNow Virtual Agent wants to hand control back over to the primary bot. Possible values: * true: Return control to the primary bot. * false: Keep control. {#bot-POST-integration__ul_zql_jkx_zmb} Data type: Boolean Default: false |
| userId | Identifier of the end user who is interacting with the bot. Data type: String |
[ ]
{#bot-POST-integration__table_bql_jkx_zmb}
### Start a conversation using the START_CONVERSATION action to start a
conversation
The following example shows how to use the START_CONVERSATION action to start a
conversation with Virtual Agent. This call directs the user to the greeting
topic.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "asd2423-sda23-qwe23-we23",
"action": "START_CONVERSATION",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "beth.anglin",
"emailId": "beth.anglin@example.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"asd2423-sda23-qwe23-we23",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"beth.anglin",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.",
"maskType":"NONE"
},
{
"uiType":"TopicPickerControl",
"group":"DefaultPicker",
"nluTextEnabled":false,
"promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type help any time when you need help.",
"label":"Show me everything",
"options":[
{
"label":"b2b topic",
"value":"2bb7bd7670de6010f877c7f188266fc7",
"enabled":true
},
{
"label":"Live Agent Support.",
"value":"ce2ee85053130010cf8cddeeff7b12bf",
"enabled":true
}
]
}
],
"score":1
}
### Transfer a conversation to Live Agent using utterance {#bot-POST-integration__example_e31_srx_sqb}
The following example illustrates how to transfer a conversation to Live Agent, bypassing the greeting topic, by passing `agent` as an utterance in the
message.text parameter. Possible utterance values are defined in the
sys_cs_contextual_action table. For additional information on contextual actions, see [Contextual actions for custom chat
integrations](https://www.servicenow.com/docs/access?context=contextual-actions&version=yokohama&pubname=yokohama-conversational-interfaces&ft:locale=en-US).
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data " {
"requestId": "322bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "agent",
"typed": true
},
"userId": "abel.tuter",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"322bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"agent",
"typed":true
},
"userId":"abel.tuter",
"body":[
{
"uiType":"Picker",
"group":"DefaultPicker",
"required":true,
"nluTextEnabled":false,
"label":"I want to be sure I got this right. What item best describes what you want to do?",
"itemType":"List",
"style":"list",
"multiSelect":false,
"options":[
{
"label":"Live Agent Support.",
"value":"Live Agent Support.",
"renderStyle":"data",
"enabled":false
},
{
"label":"Virtual Agent Capabilities.",
"value":"Virtual Agent Capabilities.",
"renderStyle":"data",
"enabled":false
},
{
"label":"I want something else",
"value":"-1",
"renderStyle":"data",
"enabled":false
}
],
"scriptedData":null
}
],
"score":1
}
### Transfer a conversation to Live Agent Support based on the user's selection {#bot-POST-integration__example_f31_srx_sqb}
The following example shows transferring the conversation to Live Agent Support based on
the user's selection from the prior interaction.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data "{
"requestId": "322bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "Live Agent Support.",
"typed": true
},
"userId": "abel.tuter",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
} "
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"322bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"Live Agent Support.",
"typed":true
},
"userId":"abel.tuter",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Please stand by while I connect you to a live agent."
}
],
"agentChat":true,
"score":1
}
### End a Virtual Agent conversation by setting the action parameter
The following example shows how to end a Virtual Agent conversation by
setting the action parameter to `END_CONVERSATION`.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "s345ew-sjg554-qwe23-we23",
"action": "END_CONVERSATION",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "b2b topic",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "beth.anglin",
"emailId": beth.anglin@example.com,
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response endpoint
showing the conversation ended.
{
"requestId":"s345ew-sjg554-qwe23-we23",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"beth.anglin",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE"
}
],
"score":1
}
### End a Live Agent conversation by setting the action parameter {#bot-POST-integration__example_fxw_jbc_s4b}
The following example shows how to end a Live Agent conversation by setting
the action parameter to `END_CONVERSATION`.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "sad-sjg554-qwe23-we23",
"action": "END_CONVERSATION",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "beth.anglin",
"emailId": "beth.anglin@example.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response endpoint
showing the conversation ended.
{
"requestId":"sad-sjg554-qwe23-we23",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"beth.anglin",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE"
}
],
"completed":true,
"score":1
}
### Use commands defined in the sys_cs_contextual_action table as an utterance to start a
conversation with Virtual Agent
The following example shows how to use the Hi command defined in the
sys_cs_contextual_action table as an utterance to start a conversation with Virtual Agent instead of setting the action parameter to
`START_CONVERSATION` as shown in prior examples. This example shows using
one of the language variants of the Hi command, "hola".
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data "{
"requestId": "302bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "hola",
"typed": true
},
"userId": "fred.ludy",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"hola",
"typed":true
},
"userId":"fred.ludy",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.",
"maskType":"NONE"
},
{
"uiType":"TopicPickerControl",
"group":"DefaultPicker",
"nluTextEnabled":false,
"promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type hellllp! any time when you need help.",
"label":"Show me everything",
"options":[
{
"label":"boolean check",
"value":"1b5257a1db712010d3d6d9595e9619f3",
"enabled":true
},
{
"label":"Test_table_datepicker",
"value":"6515f0cadb4220108249f7541d961980",
"enabled":true
},
{
"label":"Test File upload",
"value":"76c1f4b2db7520108249f7541d9619a7",
"enabled":true
},
{
"label":"Test B2B 2",
"value":"8373e55cdb8120108249f7541d96196d",
"enabled":true
},
{
"label":"FAQ Conversation Builder_Global",
"value":"9f3114a3dbc520108249f7541d961981",
"enabled":true
},
{
"label":"Get to know you",
"value":"a443dd6adb812010d3d6d9595e961954",
"enabled":true
},
{
"label":"Get to know you_Global",
"value":"b1a56b87db8120108249f7541d9619b2",
"enabled":true
},
{
"label":"Live Agent Support.",
"value":"ce2ee85053130010cf8cddeeff7b12bf",
"enabled":true
},
{
"label":"Apply for PTO_B2B NLU",
"value":"d948c94cdb052010d3d6d9595e961969",
"enabled":true
}
]
}
],
"score":1
}
### Use commands defined in the sys_cs_contextual_action table as an utterance to end a
conversation
The following example shows how to use the Bye command defined in the
sys_cs_contextual_action table as an utterance to end a conversation with Virtual Agent instead of setting action to
`END_CONVERSATION` as shown in prior examples. This example shows using one
of the language variants of the Bye command, "choa".
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data "{
"requestId": "302bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "choa",
"typed": true
},
"userId": "fred.ludy",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"chao",
"typed":true
},
"userId":"fred.ludy",
"body":[
{
"uiType":"Picker",
"group":"DefaultPicker",
"required":true,
"nluTextEnabled":false,
"label":"Please make a selection.",
"itemType":"List",
"style":"list",
"multiSelect":false,
"options":[
{
"label":"End conversation",
"value":"1",
"renderStyle":"data",
"enabled":false
},
{
"label":"Cancel",
"value":"0",
"renderStyle":"data",
"enabled":false
}
],
"scriptedData":null
}
],
"score":1
}
### Change an ongoing conversation using the SWITCH action parameter
The following example shows how to use the `SWITCH`
action parameter to change an ongoing conversation to the topic that
matches what is specified in the intent.id parameter.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "sdfsfs-hgfhg-34fssd-zxcz-sd43",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"action": "SWITCH",
"intent" : {
"id": "Saloon Vehicle"
},
"message":{
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "Guest",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response endpoint
showing the VA switched to the new topic.
{
"requestId":"sdfsfs-hgfhg-34fssd-zxcz-sd43",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"Guest",
"body":[
{
"uiType":"InputText",
"group":"DefaultText",
"required":true,
"nluTextEnabled":false,
"label":"limo input:",
"maskType":"NONE"
}
],
"score":1
}
### Obtain a Natural Language Understanding (NLU) confidence score
for an utterance {#bot-POST-integration__example_onb_ltc_s4b}
The following example shows how to obtain a NLU confidence score for an utterance if NLU is enabled in VA.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "sdfsfs-hgfhg-34fssd-zxcz-sd43",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "most popular choice",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "Guest",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response endpoint
showing the NLU confidence score.
{
"requestId":"sdfsfs-hgfhg-34fssd-zxcz-sd43",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"most popular choice",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"Guest",
"body":[
{
"uiType":"InputText",
"group":"DefaultText",
"required":true,
"nluTextEnabled":false,
"label":"model input:",
"maskType":"NONE"
}
],
"score":"0.92"
}
### Transfer a conversation to Live Agent in a specific queue
The following example shows how to transfer a conversation to Live Agent in a specific queue. You must first set up your queues with specific conditions. You then pass those conditions as contextVariables in
the request body. For additional information on creating a work item queue, see [Create a work item queue](https://www.servicenow.com/docs/access?context=awa-create-queue&version=yokohama&pubname=yokohama-servicenow-platform&ft:locale=en-US).
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "34re-dasd-qwe23-dsds", // Unique value for a message (hash)
"enterpriseId": "ServiceNow", // ServiceNow (Optional
"nowBotId": "A85PWLERF", // In case of multiple ServiceNow secondary bots (one for HR, one for ITSM)
"action":"AGENT", // Actions to close conversation. Other possible value is END_CONVERSATION
"clientSessionId": "", // Client conversation id
"nowSessionId": "", // ServiceNow conversation id
"message":{
"text": "How are you?", // User passed message
"typed": true, // typed or clicked
"clientMessageId": "ABC-123"
},
"userId": "abraham.lincoln", // User's id in their system
"emailId": "abraham.lincoln@example.com",
"timestamp": 1588824102,
"timezone": "America/New_York",
"contextVariables":{
"b2b_category":"humanresource"
}
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"34re-dasd-qwe23-dsds",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"How are you?",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"abraham.lincoln",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"I am sorry but I didn't understand your request.",
"maskType":"NONE"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Please try giving me your request in a different way. I'm currently better at understanding short sentences.",
"maskType":"NONE"
},
{
"uiType":"TopicPickerControl",
"group":"DefaultPicker",
"nluTextEnabled":false,
"promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type help any time when you need help.",
"label":"Show me everything",
"options":[
{
"label":"Live Agent Support.",
"value":"ce2ee85053130010cf8cddeeff7b12bf",
"enabled":true
}
]
}
],
"score":0
}
### Transfer a public application/pdf attachment file {#bot-POST-integration__example_yr4_2ry_lqb}
This example shows how to transfer a public application/pdf attachment.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: BOT_Token" \
--data "{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "U94CSJLEN",
"message": {
"attachment": {
"clientAttachmentId": "my-unique-identifier",
"contentType": "application/pdf",
"fileName": "MY PDF TEST",
"url": "http://www.africau.edu/images/default/sample.pdf"
}
},
"userId": "U94CSJLEN",
"emailId": "admin@example.com"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId":"U94CSJLEN",
"message":{
"attachment":{
"clientAttachmentId":"my-unique-identifier",
"contentType":"application/pdf",
"fileName":"MY PDF TEST",
"url":"http://www.africau.edu/images/default/sample.pdf"}
},
"userId":"U94CSJLEN",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"File got",
"maskType":"NONE",
"itemType":"outputtext"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE",
"itemType":"outputtext"
}
],
"completed":true,
"score":1
}
### Transfer a video/mpeg attachment {#bot-POST-integration__example_uyn_mwy_lqb}
This example shows the request/response for uploading a video/mpeg attachment.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: BOT_TOKEN" \
--data "{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "U94CSJLEN",
"message": {
"attachment": {
"clientAttachmentId": "my-unique-identifier10",
"contentType": "video/mpeg",
"fileName": "MY TEST10.mp4",
"url": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4"
}
},
"userId": "U94CSJLEN",
"emailId": "admin@example.com"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId":"U94CSJLEN",
"message":{
"attachment":{
"headers":{
"Authorization":"Basic amFzbWluZS53YWRod2FuaWE6VGVzdGluZ0AxMjM="
},
"clientAttachmentId":"my-unique-identifier10",
"contentType":"video/mpeg",
"fileName":"MY TEST10.mp4",
"url":"https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4"
}
},
"userId":"U94CSJLEN",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"File got",
"maskType":"NONE",
"itemType":"outputtext"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE","itemType":"outputtext"
}
],
"completed":true,
"score":1
}
### Transfer a image/jpeg attachment {#bot-POST-integration__example_nnb_nwy_lqb}
This example shows the request/response for uploading a image/jpeg attachment.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: BOT_TOKEN" \
--data "{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "U94CSJLEN",
"message": {
"attachment": {
"clientAttachmentId": "my-unique-identifier10",
"contentType": "image/jpeg",
"fileName": "MY TEST10.jpg",
"url": "https://image.imagestock.com/image-photo/pink-butterfly-isolated-on-white-260nw-1218104047.jpg"
}
},
"userId": "U94CSJLEN",
"emailId": "admin@example.com"
}"
--user "username":"password"
The following is the response body sent from the VA to the configured response
endpoint.
{
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId":"U94CSJLEN",
"message":{
"attachment":{
"headers":{
"Authorization":"Basic amFzbWluZS53YWRod2FuaWE6VGVzdGluZ0AxMjM="
},
"clientAttachmentId":"my-unique-identifier10",
"contentType":"image/jpeg",
"fileName":"MY TEST10.jpg",
"url":"https://image.imagestock.com/image-photo/pink-butterfly-isolated-on-white-260nw-1218104047.jpg"
}
},
"userId":"U94CSJLEN",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"File got",
"maskType":"NONE",
"itemType":"outputtext"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE",
"itemType":"outputtext"
}
],
"completed":true,
"score":1
}