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.

VA Bot Integration - POST /sn_va_as_service/bot/integration

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

Table 1. Path parameters
Name Description
None
Table 2. Query parameters
Name Description
None

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.

Table 4. Request headers
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 5. Response headers
Header Description
None

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.

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.

VA response body parameters

Response body sent from the VA to the configured response endpoint.

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

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

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.

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.
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
  • DefaultPicker
    • Picture: Items appear in a carousel.
    • List: Items appear in a dropdown-style list.

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.

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.

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.

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

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

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.
Possible values:
  • ActionMsg
  • DefaultOutputCard

    OutputCard

  • DefaultDate
    • Date
    • DateTime
    • Time
  • DefaultGroupedPartsOutputControl

    GroupedPartsOutputControl

  • DefaultHtml

    OutputHtml

  • DefaultOutputImage

    OutputImage

  • DefaultOutputLink

    OutputLink

  • DefaultText
    • InputText
    • OutputText
    • FileUpload
  • DefaultPicker
    • Picker
    • TopicPickerControl
    • Boolean

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

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.

Data type: Boolean

Default: false
userId Identifier of the end user who is interacting with the bot.

Data type: String

Example: 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 
}

Example: Transfer a conversation to Live Agent using utterance

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.

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
}

Example: Transfer a conversation to Live Agent Support based on the user's selection

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
}

Example: 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
}

Example: End a Live Agent conversation by setting the action parameter

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
}

Example: 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 
}

Example: 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 
}

Example: 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
}

Example: Obtain a Natural Language Understanding (NLU) confidence score for an utterance

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" 
}

Example: 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.

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
}

Example: Transfer a public application/pdf attachment file

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
}

Example: Transfer a video/mpeg attachment

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
}

Example: Transfer a image/jpeg attachment

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
}