AWA Inbox Actions API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 9 minutes to read

    • The AWA Inbox Actions API provides endpoints to accept or reject a work item on behalf of an agent. This API also retrieves reject reasons for rejected work items.

    This API requires the Advanced Work Assignment (com.glide.awa) plugin and awa_integration_user role. For more information, refer to Advanced Work Assignment.

    AWA Inbox Actions – GET /awa/inbox/actions/reject_reasons/{channel_id}

    Gets the work item reject reasons for a specified service channel.

    URL format

    Versioned URL: /api/now/awa/inbox/actions/reject_reasons/{channel_id}

    Default URL: /api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}

    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
    channel_id Sys_id of a service channel listed in the Service Channels [awa_service_channel] table. For information, see .
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    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. 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.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. A bad request type or malformed request was detected.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden.
    Possible reasons:
    • The user doesn't have the awa_integration_user role.
    • The value of the glide.awa.enabled property isn't true. This property is listed in the System Property [sys_property] table if the Advanced Work Assignment (com.glide.awa) plugin is installed. For more information, see Components installed with Advanced Work Assignment.
    404 Record not found. The channel ID provided is not valid.
    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)

    Name Description
    display_value Display value of the Reason field in the Reject Reasons [awa_reject_reason] table.

    Data type: String
    order Order in which the reject reasons are listed in the agent inbox.

    Data type: Number
    value Value of the reject reason field stored in the database.

    Data type: String
    Sys_id Sys_id of a rejection reason for this service channel.

    Data type: String

    Table: Reject Reasons [awa_reject_reason]

    The following example shows how to retrieve reject reasons for the Chat service channel.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Response body displaying rejected tasks with reasons for rejection.

    {
  "result": [
    {
      "order": 2,
      "value": "Not my expertise",
      "display_value": "Not my expertise",
      "sys_id": "31e3fa29b38023002e7b6e5f26a8dc17"
    },
    {
      "order": 1,
      "value": "Busy",
      "display_value": "Busy",
      "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
    }
  ]
}

    AWA Inbox Actions – POST /awa/inbox/actions/accept

    Accepts a work item in Pending Accept state on behalf of an agent.

    URL format

    Versioned URL: /api/now/{api_version}/awa/inbox/actions/accept

    Default URL: /api/now/awa/inbox/actions/accept

    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
    Table 8. Query parameters
    Name Description
    None
    Table 9. Request body parameters (XML or JSON)
    Name Description
    agent_id Sys_id of the agent listed.

    Data type: String

    Table: User [sys_user]
    work_item_id Sys_id of the work item.
    The work item must meet the following criteria:
    • Work item must be assigned to the specified agent.
    • Work item must be in Pending Accept state.

    Data type: String

    Table: AWA Work Item [awa_work_item]

    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 10. Request headers
    Header Description
    Accept Data format of the response 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.
    400 Invalid request.
    Possible reasons:
    • Missing agent ID.
    • Missing work item ID.
    • Work item is assigned to a different agent.
    • Work item isn't in pending accept state.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden.
    Possible reasons:
    • The user doesn't have the awa_integration_user role.
    • The value of the glide.awa.enabled property isn't true. This property is listed in the System Property [sys_property] table if the Advanced Work Assignment (com.glide.awa) plugin is installed. For more information, see Components installed with Advanced Work Assignment.
    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)

    Name Description
    documentTable Name of the table listing the document assigned to this work item.

    Data type: String
    documentSysId Sys_id of the document record assigned to the task. Located in the table named in the documentTable field.

    Data type: String
    error Details describing an error encountered during the request process.

    Data type: Object

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail Details of the error encountered during the request process.
    Possible values:
    • Missing agent ID: The agent_id wasn't provided in the request body.
    • Missing work item ID: The work_item_id wasn't provided in the request body.
    • Work item is assigned to a different agent – The specified work item is not assigned to the specified agent.
    • Wrong work item ID – The work item provided in the request body is inaccurate or does not exist.
    • Work item is not in pending accept state – The work item provided in the request body is in a state other than Pending Accept.

    Data type: String
    error.message Message for the error encountered during the request process. The description is provided in the error.detail property.

    Data type: String
    status Status of an unsuccessful request. This property is only included in the response if there is an error.

    Valid value: failure

    Data type: String

    cURL request

    The following example shows how to change the state of a selected agent's work item from Pending Accept to Accepted.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/accept" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
 \"work_item_id\":\"fd69abfc878b01101ae365b83cbb35fe\"
}" \
--user 'username':'password'

    The response body lists the sys_id and table of the document related to the work item.

    {
  "result": {
    "documentSysId": "57af7aec73d423002728660c4cf6a71c",
    "documentTable": "incident"
  }
}

    AWA Inbox Actions – POST /awa/inbox/actions/reject

    Rejects a work item in Pending Accept state on behalf of an agent. On success, Assigned to field is empty and the value of the Rejected field is true for the specified work item.

    URL format

    Versioned URL: /api/now/{api_version}/awa/inbox/actions/reject

    Default URL: /api/now/awa/inbox/actions/reject

    Supported request parameters

    Table 13. 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 14. Query parameters
    Name Description
    None
    Table 15. Request body parameters (XML or JSON)
    Name Description
    agent_id Sys_id of the agent listed.

    Data type: String

    Table: User [sys_user]
    reject_reason_id Sys_id of a rejection reason for this service channel.

    Data type: String

    Table: Reject Reasons [awa_reject_reason]
    work_item_id Sys_id of the work item.
    The work item must meet the following criteria:
    • Work item must be assigned to the specified agent.
    • Work item must be in Pending Accept state.

    Data type: String

    Table: AWA Work Item [awa_work_item]

    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 16. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 17. 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 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Invalid request.
    Possible reasons:
    • Missing agent ID.
    • Missing work item ID.
    • Missing reject reason ID.
    • Work item is assigned to a different agent.
    • Work item isn't in pending accept state.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden.
    Possible reasons:
    • The user doesn't have the awa_integration_user role.
    • The value of the glide.awa.enabled property isn't true. This property is listed in the System Property [sys_property] table if the Advanced Work Assignment (com.glide.awa) plugin is installed. For more information, see Components installed with Advanced Work Assignment.
    404 Not found. The requested item was not found.
    Possible reasons:
    • Wrong agent ID – There is no record for the specified user.
    • Wrong reject reason ID – There is no record for the specified reject reason.
    • Wrong work item ID – There is no record for the specified work item.
    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)

    Name Description
    agent_id Sys_id of the agent listed.

    Data type: String

    Table: User [sys_user]
    error Details describing an error encountered during the request process.

    Data type: Object

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail Details of the error encountered during the request process.
    Possible values:
    • Missing agent ID – The agent_id was not provided in the request body.
    • Missing reject reason item ID – The reject_reason_id was not provided in the request body.
    • Missing work item ID: The work_item_id wasn't provided in the request body.
    • There is no record for awa_reject_reason : <reason_sys_id> – The reject_reason_id provided in the request body does not have a matching record in the Reject Reasons [awa_reject_reason] table.
    • There is no record for awa_work_item : <work_item_sys_id> – The work_item_id provided in the request body does not have a matching record in the AWA Work Item [awa_work_item] table.
    • There is no record for sys_user : <agent_sys_id> – The agent_id provided in the request body does not have a matching record in the User [sys_user] table.
    • Work item is not in pending accept state: The work item provided in the request body is in a state other than Pending Accept.

    Data type: String
    error.message Message for the error encountered during the request process. The description is provided in the error.detail property.

    Data type: String
    status Status of an unsuccessful request. This property is only included in the response if there is an error.

    Valid value: failure

    Data type: String
    reject_reason_id Sys_id of a rejection reason for this service channel.

    Data type: String

    Table: Reject Reasons [awa_reject_reason]
    work_item_id Sys_id of the work item.

    Data type: String

    The following example shows how to reject an assigned work item with the "not my expertise" reason.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
    \"work_item_id\":\"3ed5df4d87cf01101ae365b83cbb35af\",
    \"reject_reason_id\":\"31e3fa29b38023002e7b6e5f26a8dc17\"
}" \
--user 'username':'password'

    Successful output displays the same work item, reject reason, and user ID provided in the request body. The specified work item in the AWA Work Item [awa_work_item] table has an empty Assigned to field and the value of the Rejected field is true.

    {
  "result": {
    "work_item_id": "3ed5df4d87cf01101ae365b83cbb35af",
    "reject_reason_id": "31e3fa29b38023002e7b6e5f26a8dc17",
    "agent_id": "46c9e158a9fe198101d44d0d22cb640d"
  }
}