{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":454,"path":"api-reference/rest-apis/agent-api.md","title":"AWA Agent API","bundle":null,"doc_type":null,"release":"australia","body":"\n# AWA Agent API\n\nThe AWA \\(Advanced Work Assignment\\) Agent API provides endpoints to manage agent presence, channel availability, and workload.\n\nThis API requires the Advanced Work Assignment \\(com.glide.awa\\) plugin and the 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 Agent - GET /now/awa/agents/\\{user\\_id\\}\n\nReturns the current agent presence state and channel availability.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/agents/{user_id}`\n\nDefault URL: `/api/now/awa/agents/{user_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\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\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
\n\nuser\\_id\n\n\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
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nHeader\n\n\n\nDescription\n\n
\n\npresence.channels.available\n\n\n\nFlag that indicates whether the channel is available. Possible values:\n\n- true: Channel is available.\n- false: Channel isn't available.\n\nData type: Boolean\n\n
\n\npresence.channels.sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\npresence.sys\\_id\n\n\n\nPresence state sys\\_id. Data type: String\n\nTable: Presence States \\[awa\\_presence\\_state\\]\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\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
\n\nContent-Type\n\n\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|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\n
\n\nStatus code\n\n\n\nDescription\n\n
\n\n200\n\n\n\nSuccessful. The request was successfully processed.\n\n
\n\n400\n\n\n\nBad Request. A bad request type or malformed request was detected.\n\n
\n\n401\n\n\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n
\n\n403\n\n\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
\n\n404\n\n\n\nNot found. The requested item wasn't found.\n\n
\n\n500\n\n\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n
### Response body parameters \\(JSON or XML\\)\n\n\n
\n\nParameter\n\n\n\nDescription\n\n
\n\nerror\n\n\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
\n\nerror.detail\n\n\n\nDetails of the error encountered during the request process. Data type: String\n\n
\n\nerror.message\n\n\n\nMessage for the error encountered during the request process. Each error message has a corresponding description in the **detail** property.Possible values:\n\n- `Record Not Found`: Information provided in the request body is inaccurate or doesn't exist.\n- `User Not Authenticated`: User doesn't have the awa\\_integration\\_user role.\n\nData type: String\n\n
\n\npresence\n\n\n\nInformation about an agent's current presence state and channel. Data type: Object\n\n```\n\"presence\": {\n \"available\": Boolean,\n \"channels\": [Array],\n \"name\": \"String\",\n \"sys_id\": \"String\"\n}\n```\n\n
\n\npresence.available\n\n\n\nFlag that indicates whether the agent is available. Possible values:\n\n- true: Agent is available.\n- false: Agent isn't available.\n\nData type: Boolean\n\n
\n\npresence.channels\n\n\n\nList of objects that describe the available channels of communication with the agent. Data type: Array of Objects\n\n```\n\"channels\": [\n {\n \"available\": Boolean,\n \"name\": \"String\",\n \"sys_id\": \"String\"\n }\n]\n```\n\n
\n\npresence.channels.available\n\n\n\nFlag that indicates whether the channel is available. Possible values:\n\n- true: Channel is available.\n- false: Channel isn't available.\n\nData type: Boolean\n\n
\n\npresence.channels.name\n\n\n\nChannel name, such as Chat or Phone. Data type: String\n\n
\n\npresence.channels.restrict\\_update\n\n\n\nFlag that indicates whether the user can restrict updates, that is, select the channel for availability.Possible values:\n\n- true: The user can select this channel for availability.\n- false: The user can't select this channel for availability.\n\nData type: Boolean\n\n
\n\npresence.channels.service\\_channel\\_type\n\n\n\nService channel type, such as chat. Possible values vary depending on plugins installed.Data type: String\n\n
\n\npresence.channels.sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\npresence.name\n\n\n\nName of the agent's presence state. Possible values:\n\n- Available\n- Unavailable\n\nData type: String\n\n
\n\npresence.restrict\\_update\n\n\n\nFlag that indicates whether the user can restrict updates. Possible values:\n\n- true: User can restrict updates.\n- false: User can't restrict updates.\n\nData type: Boolean\n\n
\n\npresence.sys\\_id\n\n\n\nPresence state sys\\_id. Data type: String\n\nTable: Presence States \\[awa\\_presence\\_state\\]\n\n
\n\nstatus\n\n\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
\n\nsys\\_id\n\n\n\nAgent sys\\_id. Data type: String\n\n
\n\nworkItem\n\n\n\n**workItem**: Information about the work item that is associated with the event.\n\n Data type: String\n\n
\n\nworkItem.document\n\n\n\n**workItem.document**: List of documents associated with the work item task.Data type: String\n\n
\n\nworkItem.document.sys\\_id\n\n\n\n**workItem.document.sys\\_id**: Sys\\_id of the document assigned to the work item task.Data type: String\n\n
\n\nworkItem.document.table\n\n\n\n**workItem.document.table**: Name of the document table assigned to the task.Data type: String\n\n
\n\nworkItem.previousWorkItem\n\n\n\n**workItem.previousWorkItem**: Sys\\_id of the previous work item for the same document ID. For the non-transfer work items this value is empty.Data type: String\n\n
\n\nworkItem.serviceChannel\n\n\n\n**workItem.serviceChannel**: List of service channels associated with the work item task.Data type: String\n\n
\n\nworkItem.serviceChannel.name\n\n\n\n**workItem.serviceChannel.name**: Name of the service channel, such as Chat or Phone.Data type: String\n\n
\n\nworkItem.serviceChannel.sys\\_id\n\n\n\n**workItem.serviceChannel.sys\\_id**: Sys\\_id of the service channel.Data type: String\n\n
\n\nworkItem.size\n\n\n\n**workItem.size**: Agent's capacity used when this work item is assigned to the agent.Data type: String\n\n
\n\nworkItem.sys\\_id\n\n\n\n**workItem.sys\\_id**: Sys\\_id of the work item that was accepted or offered.Data type: String\n\n
\n\nworkItem.isQueueTransferred\n\n\n\n**workItem.isQueueTransferred**: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't.Data type: Boolean\n\n
\n\nworkitem.isAutoAccepted\n\n\n\n**workItem.isAutoAccepted**: Flag that indicates whether the work item was automatically accepted by the system. Set to true if the work item was auto-accepted.Data type: Boolean\n\n
### Sample cURL request\n\n```\ncurl -X GET \\\nhttps://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \\\n-H 'Accept: application/json' \\\n-H 'Content-Type: application/json' \\\n-u 'username':'password'\\\n```\n\n```\n{\n \"result\": {\n \"presence\": {\n \"name\": \"Available\",\n \"sys_id\": \"0b10223c57a313005baaaa65ef94f970\",\n \"available\": true,\n \"channels\": [\n {\n \"name\": \"Chat\",\n \"available\": true,\n \"sys_id\": \"27f675e3739713004a905ee515f6a7c3\"\n }\n ]\n },\n \"sys_id\": \"46d44a23a9fe19810012d100cca80666\"\n }\n}\n```\n\n## AWA Agent - GET /now/awa/agents/\\{user\\_id\\}/capacities\n\nReturns an agent's channel capacities, universal capacity, and the current workload to see if the agent can handle a case.\n\nUse the [AWA Agent - PUT /now/awa/agents/\\{user\\_id\\}/capacities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agent-api.md) method to modify the channel and universal capacities of an agent.\n\nSee also:\n\n- [Service channel capacity and utilization](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-service-channel-capacity.md)\n- [Create or configure a service channel](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-create-service-channel.md)\n- [Configure an agent's maximum universal capacity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-universal-capacity.md)\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/agents/{user_id}/capacities`\n\nDefault URL: `/api/now/awa/agents/{user_id}/capacities`\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\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\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
\n\nuser\\_id\n\n\n\nSys\\_id of the agent listed.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n
|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\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|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\n
\n\nStatus code\n\n\n\nDescription\n\n
\n\n200\n\n\n\nSuccessful. The request was successfully processed.\n\n
\n\n400\n\n\n\nBad Request. A bad request type or malformed request was detected.\n\n
\n\n401\n\n\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n
\n\n403\n\n\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
\n\n404\n\n\n\nNot found. The requested item wasn't found.\n\n
\n\n500\n\n\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n
### Response body parameters \\(JSON or XML\\)\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nchannels\n\n\n\nList of objects that describe the available channels of communication with the agent. ```\n\"channels\": [\n {\n \"channel_sys_id\": \"String\",\n \"current_workload\": Number,\n \"max_capacity\": Number\n }\n]\n```\n\n Data type: Array\n\n
\n\nchannels.channel\\_sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\nchannels.current\\_workload\n\n\n\nNumber of work items on a specific service channel currently assigned to the agent.Data type: Number\n\n
\n\nchannels.max\\_capacity\n\n\n\nMaximum workload on a specific service channel that the agent can be actively assigned to at a time. Data type: String\n\n
\n\nerror\n\n\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
\n\nerror.detail\n\n\n\nDetails of the error encountered during the request process. Data type: String\n\n
\n\nerror.message\n\n\n\nMessage for the error encountered during the request process. The description is provided in the **error.detail** property.Data type: String\n\n
\n\nstatus\n\n\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
\n\nuniversal\\_capacity\n\n\n\nMaximum capacity for the agent across all service channels. If an agent's current workload equals the maximum universal capacity, additional work items won't be assigned to the agent. This property only returns if a universal capacity record exists for this agent.\n\nData type: Number\n\n
\n\nuniversal\\_workload\n\n\n\nNumber of work items across all service channels currently assigned to the specified agent.This property only returns if a universal capacity record exists for the agent.\n\n Data type: Number\n\n
### Sample cURL request\n\nThe following example shows how to get the capacity and workload values for a user.\n\n```\ncurl \"https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user 'username':'password'\n```\n\nA successful response includes capacity values and workload for each channel.\n\n```\n{\n \"result\": {\n \"universal_workload\": 2,\n \"channels\": [\n {\n \"channel_sys_id\": \"27f675e3739713004a905ee515f6a7c3\",\n \"current_workload\": 2,\n \"max_capacity\": 4\n }\n ],\n \"universal_capacity\": 10\n }\n}\n```\n\n## AWA Agent - GET /now/awa/agents/\\{user\\_id\\}/presence\\_states\n\nReturns an agent's presence states and indicates whether the agent is available or in another presence state.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/agents/{user_id}/presence_states`\n\nDefault URL: `/api/now/awa/agents/{user_id}/presence_states`\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\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\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
\n\nuser\\_id\n\n\n\nSys\\_id of the agent listed.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n
|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\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|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\n
\n\nStatus code\n\n\n\nDescription\n\n
\n\n200\n\n\n\nSuccessful. The request was successfully processed.\n\n
\n\n400\n\n\n\nBad Request. A bad request type or malformed request was detected.\n\n
\n\n401\n\n\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n
\n\n403\n\n\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
\n\n404\n\n\n\nNot found. The requested item wasn't found.\n\n
\n\n500\n\n\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n
### Response body parameters \\(JSON or XML\\)\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nerror\n\n\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
\n\nerror.detail\n\n\n\nDetails of the error encountered during the request process. Data type: String\n\n
\n\nerror.message\n\n\n\nMessage for the error encountered during the request process. The description is provided in the **error.detail** property.Data type: String\n\n
\n\n<presence state>\n\n\n\nList of the agent's presence state definitions as objects. Each object describes the state and includes the agent's channels.Data type: Array\n\n ```\n{\n \"available\": Boolean,\n \"channels\": [Array],\n \"disable_inactivity_check\": Boolean,\n \"name\": \"String\",\n \"show_channels\": Boolean,\n \"sys_id\": \"String\"\n}\n```\n\n
\n\n<presence state>.available\n\n\n\nFlag that indicates whether the agent is available. Possible values:\n\n- true: Agent is available.\n- false: Agent isn't available.\n\nData type: Boolean\n\n
\n\n<presence state>.channels\n\n\n\nList of objects that describe the available channels of communication with the agent. Data type: Array\n\n ```\n\"channels\": [\n {\n \"available\": Boolean,\n \"name\": \"String\",\n \"restrict_update\": Boolean,\n \"service_channel_type\": \"String\",\n \"sys_id\": \"String\"\n }\n]\n```\n\n
\n\n<presence state>.channels.available\n\n\n\nFlag that indicates whether the channel is available. Possible values:\n\n- true: Channel is available.\n- false: Channel isn't available.\n\nData type: Boolean\n\n
\n\n<presence state>.channels.name\n\n\n\nChannel name, such as Chat or Phone. Data type: String\n\n
\n\n<presence state>.channels.sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\n<presence state>.disable\\_inactivity\\_check\n\n\n\nFlag that indicates whether to check for inactivity of this presence state.Valid values:\n\n- true: The presence state inactivity check is disabled.\n- false: The presence state inactivity check is enabled.\n\n Data type: Boolean\n\n Default: false\n\n For information on how to modify this setting, see [Configure agent presence states](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-configure-agent-presence.md).\n\n
\n\n<presence state>.name\n\n\n\nName of the agent's presence state. The presence states installed by default are `Available`, `Away`, and `Offline`.Data type: String\n\n
\n\n<presence state>.order\n\n\n\nOrder in which this state is displayed in the agent inbox.Data type: Number\n\n
\n\n<presence state>.show\\_channels\n\n\n\nFlag that indicates whether the agent has permission to change presence state, for example, from available to away.Valid values:\n\n- true: The user has permission to change the presence.\n- false: The user is restricted from changing the presence.\n\n Data type: Boolean\n\n
\n\n<presence state>.sys\\_id\n\n\n\nPresence state sys\\_id. Data type: String\n\nTable: Presence States \\[awa\\_presence\\_state\\]\n\n
\n\nstatus\n\n\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
### Sample cURL request\n\nThe following example shows how to get the presence states for a specified agent.\n\n```\ncurl \"https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/presence_states\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user 'username':'password'\n```\n\nThe response body lists the agent's possible presence states and indicates that the agent is available.\n\n```\n{\n \"result\": [\n {\n \"name\": \"Available\",\n \"order\": 0,\n \"show_channels\": false,\n \"sys_id\": \"0b10223c57a313005baaaa65ef94f970\",\n \"available\": true,\n \"channels\": [\n {\n \"name\": \"Chat\",\n \"available\": true,\n \"sys_id\": \"27f675e3739713004a905ee515f6a7c3\",\n \"restrict_update\": false,\n \"service_channel_type\": \"chat\"\n }\n ],\n \"disable_inactivity_check\": false\n },\n {\n \"name\": \"Away\",\n \"order\": 1000,\n \"show_channels\": false,\n \"sys_id\": \"41f9b8dfb31313005baa6e5f26a8dcac\",\n \"available\": false,\n \"channels\": [],\n \"disable_inactivity_check\": false\n },\n {\n \"name\": \"Offline\",\n \"order\": 2000,\n \"show_channels\": false,\n \"sys_id\": \"9cd83267575313005baaaa65ef94f98b\",\n \"available\": false,\n \"channels\": [],\n \"disable_inactivity_check\": false\n }\n ]\n}\n```\n\n## AWA Agent - PUT /now/awa/agents/\\{user\\_id\\}\n\nSets the state of a specified agent’s presence and, if provided, sets the agent’s channel availability for that state.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/agents/{user_id}`\n\nDefault URL: `/api/now/awa/agents/{user_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\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\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
\n\nuser\\_id\n\n\n\nSys\\_id of the agent.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\npresence.channels\n\n\n\nList of objects that define which channels are available for the agent.Data type: Array of Objects\n\n```\n\"channels\": [\n { \n \"available\": Boolean,\n \"sys_id\": \"String\"\n }\n] \n```\n\n
\n\npresence.channels.available\n\n\n\nFlag that indicates whether the channel is available. Possible values:\n\n- true: Channel is available.\n- false: Channel isn't available.\n\n**Note:** This setting must be specified to include channels in the response body.\n\nData type: Boolean\n\nDefault: false\n\n
\n\npresence.channels.sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\npresence.sys\\_id\n\n\n\nPresence state sys\\_id. Data type: String\n\nTable: Presence States \\[awa\\_presence\\_state\\]\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\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
\n\nContent-Type\n\n\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|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\n
\n\nStatus code\n\n\n\nDescription\n\n
\n\n200\n\n\n\nSuccessful. The request was successfully processed.\n\n
\n\n400\n\n\n\nBad Request. A bad request type or malformed request was detected.\n\n
\n\n401\n\n\n\nUnauthorized. The user credentials are incorrect or have not been passed.\n\n
\n\n403\n\n\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
\n\n404\n\n\n\nNot found. The requested item wasn't found.\n\n
\n\n500\n\n\n\nInternal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.\n\n
\n
\n\nParameter\n\n\n\nDescription\n\n
\n\nerror\n\n\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
\n\nerror.detail\n\n\n\nDetails of the error encountered during the request process. Data type: String\n\n
\n\nerror.message\n\n\n\nMessage for the error encountered during the request process. Each error message has a corresponding description in the **detail** property.Possible values:\n\n- `Record Not Found`: Information provided in the request body is inaccurate or doesn't exist.\n- `User Not Authenticated`: User doesn't have the awa\\_integration\\_user role.\n\nData type: String\n\n
\n\npresence\n\n\n\nInformation about an agent's current presence state and channel. Data type: Object\n\n```\n\"presence\": {\n \"available\": Boolean,\n \"channels\": [Array],\n \"name\": \"String\",\n \"sys_id\": \"String\"\n}\n```\n\n
\n\npresence.available\n\n\n\nFlag that indicates whether the agent is available. Possible values:\n\n- true: Agent is available.\n- false: Agent isn't available.\n\nData type: Boolean\n\n
\n\npresence.channels\n\n\n\nList of objects that describe the available channels of communication with the agent. Data type: Array of Objects\n\n```\n\"channels\": [\n {\n \"available\": Boolean,\n \"name\": \"String\",\n \"sys_id\": \"String\"\n }\n]\n```\n\n
\n\npresence.channels.available\n\n\n\nFlag that indicates whether the channel is available. Possible values:\n\n- true: Channel is available.\n- false: Channel isn't available.\n\nData type: Boolean\n\n
\n\npresence.channels.name\n\n\n\nChannel name, such as Chat or Phone. Data type: String\n\n
\n\npresence.channels.restrict\\_update\n\n\n\nFlag that indicates whether the user can restrict updates, that is, select the channel for availability.Possible values:\n\n- true: The user can select this channel for availability.\n- false: The user can't select this channel for availability.\n\nData type: Boolean\n\n
\n\npresence.channels.service\\_channel\\_type\n\n\n\nService channel type, such as chat. Possible values vary depending on plugins installed.Data type: String\n\n
\n\npresence.channels.sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\npresence.name\n\n\n\nName of the agent's presence state. Possible values:\n\n- Available\n- Unavailable\n\nData type: String\n\n
\n\npresence.restrict\\_update\n\n\n\nFlag that indicates whether the user can restrict updates. Possible values:\n\n- true: User can restrict updates.\n- false: User can't restrict updates.\n\nData type: Boolean\n\n
\n\npresence.sys\\_id\n\n\n\nPresence state sys\\_id. Data type: String\n\nTable: Presence States \\[awa\\_presence\\_state\\]\n\n
\n\nstatus\n\n\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
\n\nsys\\_id\n\n\n\nAgent sys\\_id. Data type: String\n\n
\n\nworkItem\n\n\n\n**workItem**: Information about the work item that is associated with the event.\n\n Data type: String\n\n
\n\nworkItem.document\n\n\n\n**workItem.document**: List of documents associated with the work item task.Data type: String\n\n
\n\nworkItem.document.sys\\_id\n\n\n\n**workItem.document.sys\\_id**: Sys\\_id of the document assigned to the work item task.Data type: String\n\n
\n\nworkItem.document.table\n\n\n\n**workItem.document.table**: Name of the document table assigned to the task.Data type: String\n\n
\n\nworkItem.previousWorkItem\n\n\n\n**workItem.previousWorkItem**: Sys\\_id of the previous work item for the same document ID. For the non-transfer work items this value is empty.Data type: String\n\n
\n\nworkItem.serviceChannel\n\n\n\n**workItem.serviceChannel**: List of service channels associated with the work item task.Data type: String\n\n
\n\nworkItem.serviceChannel.name\n\n\n\n**workItem.serviceChannel.name**: Name of the service channel, such as Chat or Phone.Data type: String\n\n
\n\nworkItem.serviceChannel.sys\\_id\n\n\n\n**workItem.serviceChannel.sys\\_id**: Sys\\_id of the service channel.Data type: String\n\n
\n\nworkItem.size\n\n\n\n**workItem.size**: Agent's capacity used when this work item is assigned to the agent.Data type: String\n\n
\n\nworkItem.sys\\_id\n\n\n\n**workItem.sys\\_id**: Sys\\_id of the work item that was accepted or offered.Data type: String\n\n
\n\nworkItem.isQueueTransferred\n\n\n\n**workItem.isQueueTransferred**: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't.Data type: Boolean\n\n
\n\nworkitem.isAutoAccepted\n\n\n\n**workItem.isAutoAccepted**: Flag that indicates whether the work item was automatically accepted by the system. Set to true if the work item was auto-accepted.Data type: Boolean\n\n
```\ncurl -X PUT \\\n https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \\\n-H 'Accept: application/json' \\\n-H 'Content-Type: application/json' \\\n-u 'username':'password'\\\n-d '{\"presence\": {\\\n \"sys_id\": \"0b10223c57a313005baaaa65ef94f970\",\\\n \"channels\": [{ \\\n \"sys_id\": \"0bbdedbb3b892300a2bac9bb34efc445\",\\\n \"available\": true\n}] \n}}\n```\n\n```\n{\n \"result\": {\n \"presence\": {\n \"name\": \"Available\",\n \"sys_id\": \"0b10223c57a313005baaaa65ef94f970\",\n \"available\": true,\n \"channels\": [\n {\n \"name\": \"Chat\",\n \"available\": true,\n \"sys_id\": \"27f675e3739713004a905ee515f6a7c3\"\n }\n ]\n },\n \"sys_id\": \"46d44a23a9fe19810012d100cca80666\"\n }\n}\n```\n\n## AWA Agent - PUT /now/awa/agents/\\{user\\_id\\}/capacities\n\nEnables updating an agent's maximum capacity \\(workload\\) for channel capacities and universal capacity.\n\nUse the [AWA Agent - GET /now/awa/agents/\\{user\\_id\\}/capacities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agent-api.md) method to retrieve the current channel and universal capacities of an agent.\n\nSee also:\n\n- [Service channel capacity and utilization](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-service-channel-capacity.md)\n- [Create or configure a service channel](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-create-service-channel.md)\n- [Configure an agent's maximum universal capacity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/conversational-interfaces/awa-universal-capacity.md)\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/awa/agents/{user_id}/capacities`\n\nDefault URL: `/api/now/awa/agents/{user_id}/capacities`\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\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\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
\n\nuser\\_id\n\n\n\nSys\\_id of the agent listed.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nchannels\n\n\n\nMandatory if updating the maximum value of one or more channels for the specified agent. JSON object containing one or more key-value pairs mapping the channel to its maximum capacity for each channel assigned to the agent.Data type: Object\n\n The pair is in the following format:\n\n- Key \\(channel sys\\_id\\) – Channel sys\\_id.\n\nData type: String\n\n- Value \\(maximum capacity\\) – Maximum workload on a specific service channel that the agent can be actively assigned to at a time.\n\nData type: Number\n\n\n ```\nchannels: {\"\": }\n```\n\n
\n\nuniversal\\_capacity\n\n\n\nMandatory if universal capacity is being updated. Maximum capacity for the agent across all service channels. If an agent's current workload equals the maximum universal capacity, additional work items won't be assigned to the agent. Data type: Number\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\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|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|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|404|Not found. The requested item wasn't found.|\n\n### Response body parameters \\(JSON or XML\\)\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nchannels\n\n\n\nList of objects that describe the available channels of communication with the agent. ```\n\"channels\": [\n {\n \"channel_sys_id\": \"String\",\n \"max_capacity\": Number\n }\n]\n```\n\n Data type: Array\n\n
\n\nchannels.channel\\_sys\\_id\n\n\n\nChannel sys\\_id. Data type: String\n\nTable: Service Channels \\[awa\\_service\\_channel\\]\n\n
\n\nchannels.max\\_capacity\n\n\n\nMaximum workload on a specific service channel that the agent can be actively assigned to at a time. Data type: String\n\n
\n\nerror\n\n\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
\n\nerror.detail\n\n\n\nDetails of the error encountered during the request process. Data type: String\n\n
\n\nerror.message\n\n\n\nMessage for the error encountered during the request process. The description is provided in the **error.detail** property.Data type: String\n\n
\n\nstatus\n\n\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
\n\nuniversal\\_capacity\n\n\n\nMaximum capacity for the agent across all service channels. If an agent's current workload equals the maximum universal capacity, additional work items won't be assigned to the agent. This property only returns if a universal capacity record exists for this agent.\n\nData type: Number\n\n
### Sample cURL request\n\nThe following example shows how to change the agent's universal capacity and the maximum capacity for a specified channel.\n\n```\ncurl \"https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities\" \\\n--request PUT \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n \\\"channels\\\": { \\\"27f675e3739713004a905ee515f6a7c3\\\": 6 },\n \\\"universal_capacity\\\" : 12\n}\" \\\n--user 'username':'password'\n```\n\nA successful response includes the updated capacity values.\n\n```\n{\n \"result\": {\n \"channels\": [\n {\n \"channel_sys_id\": \"27f675e3739713004a905ee515f6a7c3\",\n \"max_capacity\": 6\n }\n ],\n \"universal_capacity\": 12\n }\n}\n```\n\n"}}