Interaction Management API

Watch

Save as PDF

Share this page

Feedback

API implementation and reference

HomeVancouver API ReferenceAPI implementation and referenceAPI referenceREST API referenceInteraction Management API

Table of Contents

Interaction Management API

Release version:
Vancouver
Yokohama
Xanadu
Washington DC
UpdatedAug 3, 2023
5 minutes to read

Vancouver
API reference

The Vancouver release is no longer supported. As such, the product documentation and release notes are provided for informational purposes only, and will not be updated.

The Interaction Management API provides endpoints to create interactions.

This class requires the Interaction Logging, Routing, and Queueing plugin (com.glide.interaction).

Interaction - POST /now/interaction

Inserts or updates a record in the interaction table.

URL format

Versioned URL: /api/now/{api_version}/interaction

Default URL: /api/now/interaction

Supported request parameters

Table 1. Path parameters
Name	Description
api_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String

Table 2. Query parameters
Name	Description
None

Search:

Table 3. Request body parameters (XML or JSON)
Element	Description
channel	Required. Sys_id for the interaction connector you want to create an interaction for. Data type: String
context	A Map or a table/sys_id pair. By default, interactions have a record in the interaction_json_blob table that stores context data as a JSON object. You can point an interaction to a different record for context. Use context or context_table/context_id to define the context for an interaction. Data type: String
context_id	Document ID for a record you want to use to store context. The default is a new record in the insteraction_json_blob table. If you define the context ID, you also need to define the table. Data type: String
context_table	Context table you want to use to store interaction context for. The default is interaction_json_blob. If you define the context table, you also need to define the context ID. Data type: String
channel_metadata	Map or a table/sys_id pair. Channel metadata contains information that a connector can use to communicate through the associated channel. Data type: String
channel_metadata_id	Document ID for a record you want to use to store channel metadata. The default is a new record in the live_group_profile table. If you define the channel metadata ID, you also need to define the table. Data type: String
channel_metadata_table	Table you want to use to store channel metadata. The default is the live_group_profile table. If you define the channel metadata table, you also need to define the channel metadata ID. Data type: String
queue	Sys_id for the queue you want to associate with the interaction. Data type: String

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. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

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.

Search:

Table 6. Status codes
Status code	Description
201	Indicates the query ran successfully.
400	Indicates that one or more mandatory parameters were missing from the request.
401	Unauthorized. The user credentials are incorrect or haven't been passed.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Search:


Element	Description
assigned_to	The sys_id of the user the interaction is assigned to. Data type: String
channelMetadataDocument	The sys_id of the channel metadata document associated with the interaction. Data type: String
channelMetadataTable	The table name of the channel metadata table associated with the interaction. Data type: String
channel_metadata	Any channel metadata included for the interaction. Data type: String
closed_by	The sys_id of the user who closed the interaction. Data type: String
contextDocument	The sys_id for the context document associated with the interaction. Data type: String
contextTable	The name of the table associated with the interaction. Data type: String
number	The number of the new interaction. Data type: String
opened_for	The sys_id of the user who the interaction was opened for. Data type: String
queue	The sys_id for the queue you create the interaction for. Data type: String
state	The state the interaction is in. If you assign a queue, the state automatically changes to Queued, otherwise the default is New. Data type: String
sys_id	The sys_id of the interaction. Data type: String

Example: Sample cURL request

curl "http://instance.servicenow.com/api/now/interaction" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"channel\":\"28a59893873103002ae97e2526cb0b5d\",\"queue\":\"f3a50867b30303002186a72256a8dcb7\"}" \
--user "username":"password"

{
  "result": {
    "channel": "28a59893873103002ae97e2526cb0b5d",
    "context": {
      "present": true
    },
    "queue": "f3a50867b30303002186a72256a8dcb7",
    "state": "queued",
    "number": "IMS0000075",
    "contextDocument": "1863a6f0d9471300964f387107a8a36d",
    "contextTable": "interaction_json_blob",
    "channelMetadataDocument": "9463a6f0d9471300964f387107a8a36c",
    "channelMetadataTable": "live_group_profile",
    "channel_metadata": {
      "present": true
    },
    "sys_id": "dc63a6f0d9471300964f387107a8a36b",
    "assigned_to": "",
    "closed_by": "",
    "opened_for": ""
  }
}

Interaction - POST /now/interaction/{interaction_id}/close

Changes the state of an interaction to closed or closed complete.

URL format

Versioned URL: /api/now/{api_version}interaction/{interaction_id}/close

Default URL: /api/now/interaction/{interaction_id}/close

Supported request parameters

Table 7. Path parameters
Name	Description
api_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String
interaction_id	Sys_id for the interaction you want to close. Data type: String

Table 8. Query parameters
Name	Description
None

Table 9. Request body parameters (XML or JSON)
Name	Description
None

Headers

Table 10. Request headers
Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

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

Table 12. Status codes
Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or haven't been passed.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Search:


Element	Description
assigned_to	The sys_id of the user the interaction is assigned to. Data type: String
channelMetadataDocument	The sys_id of the channel metadata document associated with the interaction. Data type: String
channelMetadataTable	The table name of the channel metadata table associated with the interaction. Data type: String
channel_metadata	Any channel metadata included for the interaction. Data type: String
closed_by	The sys_id of the user who closed the interaction. Data type: String
contextDocument	The sys_id for the context document associated with the interaction. Data type: String
contextTable	The name of the table associated with the interaction. Data type: String
number	The number of the new interaction. Data type: String
opened_for	The sys_id of the user who the interaction was opened for. Data type: String
queue	The sys_id for the queue you create the interaction for. Data type: String
state	The state the interaction is in. If you assign a queue, the state automatically changes to Queued, otherwise the default is New. Data type: String
sys_id	The sys_id of the interaction. Data type: String

Example: Sample cURL request

curl "http://instance.servicenow.com/api/now/interaction/b243cde4208f1700964f959e0488dee8/close" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username":"password"

{
  "result": {
    "channel": "28a59893873103002ae97e2526cb0b5d",
    "context": {
      "present": true
    },
    "queue": "f3a50867b30303002186a72256a8dcb7",
    "state": "closed_complete",
    "number": "IMS0000060",
    "contextDocument": "3a43cde4208f1700964f959e0488dee7",
    "contextTable": "interaction_json_blob",
    "channelMetadataDocument": "fa43cde4208f1700964f959e0488dee8",
    "channelMetadataTable": "live_group_profile",
    "channel_metadata": {
      "present": true
    },
    "sys_id": "b243cde4208f1700964f959e0488dee8",
    "assigned_to": "",
    "closed_by": "6816f79cc0a8016401c5a33be04be441",
    "opened_for": "46d44a23a9fe19810012d100cca80666"
  }
}

Vancouver API Reference

Filters

Versions

Products