{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":471,"path":"api-reference/rest-apis/awa-inbox-actions-api.md","title":"AWA Inbox Actions API","bundle":null,"doc_type":null,"release":"australia","body":"\n# AWA Inbox Actions API\n\nThe 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.\n\nThis API requires the Advanced Work Assignment \\(com.glide.awa\\) plugin and awa\\_integration\\_user role. For more information, refer to [Advanced Work Assignment](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-overview.md).\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## AWA Inbox Actions – GET /awa/inbox/actions/reject\\_reasons/\\{channel\\_id\\}\n\nGets the work item reject reasons for a specified service channel.\n\n### URL format\n\nVersioned URL: `/api/now/awa/inbox/actions/reject_reasons/{channel_id}`\n\nDefault URL: `/api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr><tr><td>\n\nchannel\\_id\n\n</td><td>\n\nSys\\_id of a service channel.Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td id=\"entry-200-status-code\">\n\nSuccessful. The request was successfully processed.\n\n</td></tr><tr><td>\n\n400\n\n</td><td id=\"entry-400-status-code\">\n\nBad Request. A bad request type or malformed request was detected.\n\n</td></tr><tr><td>\n\n401\n\n</td><td id=\"entry-401-status-code\">\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n</td></tr><tr><td>\n\n403\n\n</td><td id=\"entry-403-status-code-awa\">\n\nForbidden.Possible reasons:\n\n-   The user doesn't have the awa\\_integration\\_user role.\n-   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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/installed-with-awa.md).\n\n</td></tr><tr><td>\n\n404\n\n</td><td>\n\nRecord not found. The channel ID provided is not valid.\n\n</td></tr><tr><td>\n\n500\n\n</td><td id=\"entry-500-status-code\">\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ndisplay\\_value\n\n</td><td>\n\nDisplay value of the Reason field in the Reject Reasons \\[awa\\_reject\\_reason\\] table.Data type: String\n\n</td></tr><tr><td>\n\norder\n\n</td><td>\n\nOrder in which the reject reasons are listed in the agent inbox.Data type: Number\n\n</td></tr><tr><td>\n\nvalue\n\n</td><td>\n\nValue of the reject reason field stored in the database.Data type: String\n\n</td></tr><tr><td>\n\nSys\\_id\n\n</td><td>\n\nSys\\_id of a rejection reason for this service channel.Data type: String\n\nTable: Reject Reasons \\[awa\\_reject\\_reason\\]\n\n</td></tr></tbody>\n</table>The following example shows how to retrieve reject reasons for the Chat service channel.\n\n```\ncurl \"https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user 'username':'password'\n```\n\nResponse body displaying rejected tasks with reasons for rejection.\n\n```\n{\n  \"result\": [\n    {\n      \"order\": 2,\n      \"value\": \"Not my expertise\",\n      \"display_value\": \"Not my expertise\",\n      \"sys_id\": \"31e3fa29b38023002e7b6e5f26a8dc17\"\n    },\n    {\n      \"order\": 1,\n      \"value\": \"Busy\",\n      \"display_value\": \"Busy\",\n      \"sys_id\": \"4e93fa29b38023002e7b6e5f26a8dc20\"\n    }\n  ]\n}\n```\n\n## AWA Inbox Actions – POST /awa/inbox/actions/accept\n\nAccepts a work item in **Pending Accept** state on behalf of an agent.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/inbox/actions/accept`\n\nDefault URL: `/api/now/awa/inbox/actions/accept`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nagent\\_id\n\n</td><td>\n\nSys\\_id of the agent listed.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n</td></tr><tr><td>\n\nwork\\_item\\_id\n\n</td><td>\n\nSys\\_id of the work item. The work item must meet the following criteria:\n\n-   Work item must be assigned to the specified agent.\n-   Work item must be in **Pending Accept** state.\n\nData type: String\n\nTable: AWA Work Item \\[awa\\_work\\_item\\]\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_qsk_1hj_mtb\"><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td id=\"entry-200-status-code\">\n\nSuccessful. The request was successfully processed.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nInvalid request. Possible reasons:\n\n-   Missing agent ID.\n-   Missing work item ID.\n-   Work item is assigned to a different agent.\n-   Work item isn't in pending accept state.\n\n</td></tr><tr><td>\n\n401\n\n</td><td id=\"entry-401-status-code\">\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n</td></tr><tr><td>\n\n403\n\n</td><td id=\"entry-403-status-code-awa\">\n\nForbidden.Possible reasons:\n\n-   The user doesn't have the awa\\_integration\\_user role.\n-   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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/installed-with-awa.md).\n\n</td></tr><tr><td>\n\n500\n\n</td><td id=\"entry-500-status-code\">\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ndocumentTable\n\n</td><td>\n\nName of the table listing the document assigned to this work item.Data type: String\n\n</td></tr><tr><td>\n\ndocumentSysId\n\n</td><td>\n\nSys\\_id of the document record assigned to the task.Data type: String\n\nTable: In the table identified in the **documentTable** field.\n\n</td></tr><tr id=\"ordr-row-error\"><td>\n\nerror\n\n</td><td>\n\nDetails describing an error encountered during the request process.Data type: Object\n\n```\n\"error\": {\n  \"detail\": \"String\",\n  \"message\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\nerror.detail\n\n</td><td>\n\nDetails of the error encountered during the request process. Possible values:\n\n-   `Missing agent ID`: The **agent\\_id** wasn't provided in the request body.\n-   `Missing work item ID`: The **work\\_item\\_id** wasn't provided in the request body.\n-   `Work item is assigned to a different agent`: The specified work item is not assigned to the specified agent.\n-   `Wrong work item ID`: The work item provided in the request body is inaccurate or doesn't exist.\n-   `Work item is not in pending accept state`: The work item provided in the request body is in a state other than **Pending Accept**.\n\nData type: String\n\n</td></tr><tr><td>\n\nerror.message\n\n</td><td>\n\nMessage for the error encountered during the request process. The description is provided in the **error.detail** property.Data type: String\n\n</td></tr><tr><td>\n\nstatus\n\n</td><td>\n\nStatus of an unsuccessful request. This property is only included in the response if there is an error.Valid value: `failure`\n\nData type: String\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following example shows how to change the state of a selected agent's work item from **Pending Accept** to **Accepted**.\n\n```\ncurl \"https://instance.service-now.com/api/now/awa/inbox/actions/accept\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n \\\"agent_id\\\":\\\"46c9e158a9fe198101d44d0d22cb640d\\\",\n \\\"work_item_id\\\":\\\"fd69abfc878b01101ae365b83cbb35fe\\\"\n}\" \\\n--user 'username':'password'\n```\n\nThe response body lists the sys\\_id and table of the document related to the work item.\n\n```\n{\n  \"result\": {\n    \"documentSysId\": \"57af7aec73d423002728660c4cf6a71c\",\n    \"documentTable\": \"incident\"\n  }\n}\n```\n\n## AWA Inbox Actions – POST /awa/inbox/actions/reject\n\nRejects 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.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/inbox/actions/reject`\n\nDefault URL: `/api/now/awa/inbox/actions/reject`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nagent\\_id\n\n</td><td>\n\nSys\\_id of the agent listed.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n</td></tr><tr><td>\n\nreject\\_reason\\_id\n\n</td><td>\n\nSys\\_id of a rejection reason for this service channel.Data type: String\n\nTable: Reject Reasons \\[awa\\_reject\\_reason\\]\n\n</td></tr><tr><td>\n\nwork\\_item\\_id\n\n</td><td>\n\nSys\\_id of the work item. The work item must meet the following criteria:\n\n-   Work item must be assigned to the specified agent.\n-   Work item must be in **Pending Accept** state.\n\nData type: String\n\nTable: AWA Work Item \\[awa\\_work\\_item\\]\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td id=\"entry-200-status-code\">\n\nSuccessful. The request was successfully processed.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nInvalid request. Possible reasons:\n\n-   Missing agent ID.\n-   Missing work item ID.\n-   Missing reject reason ID.\n-   Work item is assigned to a different agent.\n-   Work item isn't in pending accept state.\n\n</td></tr><tr><td>\n\n401\n\n</td><td id=\"entry-401-status-code\">\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n</td></tr><tr><td>\n\n403\n\n</td><td id=\"entry-403-status-code-awa\">\n\nForbidden.Possible reasons:\n\n-   The user doesn't have the awa\\_integration\\_user role.\n-   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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/installed-with-awa.md).\n\n</td></tr><tr><td>\n\n404\n\n</td><td>\n\nNot found. The requested item wasn't found.Possible reasons:\n\n-   Wrong agent ID – There is no record for the specified user.\n-   Wrong reject reason ID – There is no record for the specified reject reason.\n-   Wrong work item ID – There is no record for the specified work item.\n\n</td></tr><tr><td>\n\n500\n\n</td><td id=\"entry-500-status-code\">\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nagent\\_id\n\n</td><td>\n\nSys\\_id of the agent listed.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n</td></tr><tr id=\"ordr-row-error\"><td>\n\nerror\n\n</td><td>\n\nDetails describing an error encountered during the request process.Data type: Object\n\n```\n\"error\": {\n  \"detail\": \"String\",\n  \"message\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\nerror.detail\n\n</td><td>\n\nDetails of the error encountered during the request process. Possible values:\n\n-   `Missing agent ID` – The **agent\\_id** wasn't provided in the request body.\n-   `Missing reject reason item ID` – The **reject\\_reason\\_id** wasn't provided in the request body.\n-   `Missing work item ID`: The **work\\_item\\_id** wasn't provided in the request body.\n-   `There is no record for awa_reject_reason : <reason_sys_id>` – The **reject\\_reason\\_id** provided in the request body doesn't have a matching record in the Reject Reasons \\[awa\\_reject\\_reason\\] table.\n-   `There is no record for awa_work_item : <work_item_sys_id>` – The **work\\_item\\_id** provided in the request body doesn't have a matching record in the AWA Work Item \\[awa\\_work\\_item\\] table.\n-   `There is no record for sys_user : <agent_sys_id>` – The **agent\\_id** provided in the request body doesn't have a matching record in the User \\[sys\\_user\\] table.\n-   `Work item is not in pending accept state`: The work item provided in the request body is in a state other than **Pending Accept**.\n\nData type: String\n\n</td></tr><tr><td>\n\nerror.message\n\n</td><td>\n\nMessage for the error encountered during the request process. The description is provided in the **error.detail** property.Data type: String\n\n</td></tr><tr><td>\n\nstatus\n\n</td><td>\n\nStatus of an unsuccessful request. This property is only included in the response if there is an error.Valid value: `failure`\n\nData type: String\n\n</td></tr><tr><td>\n\nreject\\_reason\\_id\n\n</td><td>\n\nSys\\_id of a rejection reason for this service channel.Data type: String\n\nTable: Reject Reasons \\[awa\\_reject\\_reason\\]\n\n</td></tr><tr><td>\n\nwork\\_item\\_id\n\n</td><td>\n\nSys\\_id of the work item. Data type: String\n\n</td></tr></tbody>\n</table>The following example shows how to reject an assigned work item with the \"not my expertise\" reason.\n\n```\ncurl \"https://instance.service-now.com/api/now/awa/inbox/actions/reject\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n    \\\"agent_id\\\":\\\"46c9e158a9fe198101d44d0d22cb640d\\\",\n    \\\"work_item_id\\\":\\\"3ed5df4d87cf01101ae365b83cbb35af\\\",\n    \\\"reject_reason_id\\\":\\\"31e3fa29b38023002e7b6e5f26a8dc17\\\"\n}\" \\\n--user 'username':'password'\n```\n\nSuccessful 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.\n\n```\n{\n  \"result\": {\n    \"work_item_id\": \"3ed5df4d87cf01101ae365b83cbb35af\",\n    \"reject_reason_id\": \"31e3fa29b38023002e7b6e5f26a8dc17\",\n    \"agent_id\": \"46c9e158a9fe198101d44d0d22cb640d\"\n  }\n}\n```\n\n"}}