AWA Agent API

The AWA (Advanced Work Assignment) Agent API provides endpoints to manage agent presence, channel availability, and workload.

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

Parent Topic:REST API reference

AWA Agent - GET /now/awa/agents/{user_id}

Returns the current agent presence state and channel availability.

URL format

Versioned URL: /api/now/{api_version}/awa/agents/{user_id}

Default URL: /api/now/awa/agents/{user_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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.

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 (JSON or XML)

"error": {
  "detail": "String",
  "message": "String"
}

"presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}

"channels": [
  {
    "available": Boolean,
    "name": "String",
    "sys_id": "String"
  }
]

Sample cURL request

curl -X GET \
https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\

{
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

AWA Agent - GET /now/awa/agents/{user_id}/capacities

Returns an agent's channel capacities, universal capacity, and the current workload to see if the agent can handle a case.

Use the AWA Agent - PUT /now/awa/agents/{user_id}/capacities method to modify the channel and universal capacities of an agent.

See also:

• Service channel capacity and utilization
• Create or configure a service channel
• Configure an agent's maximum universal capacity

URL format

Versioned URL: /api/now/{api_version}/awa/agents/{user_id}/capacities

Default URL: /api/now/awa/agents/{user_id}/capacities

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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.

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 (JSON or XML)

"channels": [
  {
    "channel_sys_id": "String",
    "current_workload": Number,
    "max_capacity": Number
  }
]

"error": {
  "detail": "String",
  "message": "String"
}

Sample cURL request

The following example shows how to get the capacity and workload values for a user.

curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

A successful response includes capacity values and workload for each channel.

{
  "result": {
    "universal_workload": 2,
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "current_workload": 2,
        "max_capacity": 4
      }
    ],
    "universal_capacity": 10
  }
}

AWA Agent - GET /now/awa/agents/{user_id}/presence_states

Returns an agent's presence states and indicates whether the agent is available or in another presence state.

URL format

Versioned URL: /api/now/{api_version}/awa/agents/{user_id}/presence_states

Default URL: /api/now/awa/agents/{user_id}/presence_states

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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.

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 (JSON or XML)

"error": {
  "detail": "String",
  "message": "String"
}

</td></tr><tr><td>

&lt;presence state&gt;.available

</td><td>

Flag that indicates whether the agent is available. Possible values:

-   true: Agent is available.
-   false: Agent isn't available.

Data type: Boolean

</td></tr><tr><td>

&lt;presence state&gt;.channels

</td><td>

List of objects that describe the available channels of communication with the agent. Data type: Array

 ```
"channels": [
 {
  "available": Boolean,
  "name": "String",
  "restrict_update": Boolean,
  "service_channel_type": "String",
  "sys_id": "String"
 }
]

Sample cURL request

The following example shows how to get the presence states for a specified agent.

curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/presence_states" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

The response body lists the agent's possible presence states and indicates that the agent is available.

{
  "result": [
    {
      "name": "Available",
      "order": 0,
      "show_channels": false,
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3",
          "restrict_update": false,
          "service_channel_type": "chat"
        }
      ],
      "disable_inactivity_check": false
    },
    {
      "name": "Away",
      "order": 1000,
      "show_channels": false,
      "sys_id": "41f9b8dfb31313005baa6e5f26a8dcac",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    },
    {
      "name": "Offline",
      "order": 2000,
      "show_channels": false,
      "sys_id": "9cd83267575313005baaaa65ef94f98b",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    }
  ]
}

AWA Agent - PUT /now/awa/agents/{user_id}

Sets the state of a specified agent’s presence and, if provided, sets the agent’s channel availability for that state.

URL format

Versioned URL: /api/now/{api_version}/awa/agents/{user_id}

Default URL: /api/now/awa/agents/{user_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

"channels": [
  { 
    "available": Boolean,
    "sys_id": "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.

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.

"error": {
  "detail": "String",
  "message": "String"
}

"presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}

"channels": [
  {
    "available": Boolean,
    "name": "String",
    "sys_id": "String"
  }
]

curl -X PUT \
 https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\
-d '{"presence": {\
  "sys_id": "0b10223c57a313005baaaa65ef94f970",\
  "channels": [{ \
  "sys_id": "0bbdedbb3b892300a2bac9bb34efc445",\
  "available": true
}] 
}}

{
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

AWA Agent - PUT /now/awa/agents/{user_id}/capacities

Enables updating an agent's maximum capacity (workload) for channel capacities and universal capacity.

Use the AWA Agent - GET /now/awa/agents/{user_id}/capacities method to retrieve the current channel and universal capacities of an agent.

See also:

• Service channel capacity and utilization
• Create or configure a service channel
• Configure an agent's maximum universal capacity

URL format

Versioned URL: /api/now/{api_version}/awa/agents/{user_id}/capacities

Default URL: /api/now/awa/agents/{user_id}/capacities

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

</td></tr><tr><td>

universal\_capacity

</td><td>

Mandatory 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

</td></tr></tbody>
</table>

### 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](../rest-api-explorer/c_RESTAPI.md).

<table class="rest_api_request_headers"><thead><tr><th>

Header

</th><th>

Description

</th></tr></thead><tbody><tr><td>

Accept

</td><td id="accept-entry-RESTAPI">Data format of the response body. Supported types: <strong>application/json</strong> or <strong>application/xml</strong>. Default: <strong>application/json</strong></td></tr></tbody>
</table>

|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](../rest-api-explorer/c_RESTAPI.md).

|Status code|Description|
|-----------|-----------|
|200|Successful. The request was successfully processed.|
|400|Bad Request. A bad request type or malformed request was detected.|
|404|Not found. The requested item wasn't found.|

### Response body parameters \(JSON or XML\)

<table id="table_bgk_dmp_htb"><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

channels

</td><td>

List of objects that describe the available channels of communication with the agent.

 Data type: Array

</td></tr><tr><td>

channels.channel\_sys\_id

</td><td>

Channel sys\_id. Data type: String

Table: Service Channels \[awa\_service\_channel\]

</td></tr><tr><td>

channels.max\_capacity

</td><td>

Maximum workload on a specific service channel that the agent can be actively assigned to at a time. Data type: String

</td></tr><tr id="ordr-row-error"><td>

error

</td><td>

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

</td></tr><tr><td>

error.detail

</td><td>

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

</td></tr><tr><td>

error.message

</td><td>Message for the error encountered during the request process. The description is provided in the <strong>error.detail</strong> property.Data type: String</td></tr><tr><td>

status

</td><td>

Status of an unsuccessful request. This property is only included in the response if there is an error.Valid value: `failure`

Data type: String

</td></tr><tr><td>

universal\_capacity

</td><td>

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. This property only returns if a universal capacity record exists for this agent.

Data type: Number

</td></tr></tbody>
</table>

### Sample cURL request

The following example shows how to change the agent's universal capacity and the maximum capacity for a specified channel.

A successful response includes the updated capacity values.