CC Managing Agent Status

This guide describes how to manage agent status via API

Authentication

CC Campaign APIs leverage the credentials from the Integration >> API Token area in Configuration Manager.
These APIs use Basic Authentication.
The username will be the "Username" value from this screen, it is generally the tenant name
The password will vary depending on the action:

  • For any GET the "Data Request Token" will be the password.
  • For any SET the "Action Request Token" will be the password.

Authorization :Basic encodedValue

Where encodedValue is base64encode(username:password)

๐Ÿ“˜

If there are no token values

If the token values are empty you can generate the token by clicking on 'New Token'. Once a token is generated, if you would like to generate a new one, please be aware that once a new token is generated, the old one will not work anymore for anybody.

Get Status for all agents

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
Authorizationโœ“Basic Authentication where username is the value of username and the password is the value of Data Request TokenBasic bXljbGllbnRJZDpuZXZlcnRlbGxhbnlvbmU=

Path

NameRequiredDescriptionExample
ccPlatformโœ“Contact Center platform can be found in the url when accessing CC Configuration Manager.
North America starts NA
Europe starts EU
Canada starts CA
Asia Pacific starts AP
Australia starts AU
Bell Canada starts BC
Sandbox starts SB
na12
versionโœ“The API version. The current version is 1 resulting in. v1v1
tenantIdโœ“The CC Tenant name of the tenant to list agent status for. Tenant name is generally the same as the username above. It can be located in CC Configuration Manager @ Home :: Profile :: Tenant Nameacmecorp01

All Agents Status Request

curl --location --request GET 'https://{ccPlatform}.8x8.com/api/v{version}/tenants/{tenantId}/agentstatus/agents' \
--header 'Authorization: Basic {encodedValue}'

All Agent Status Response

{
    "data": [
        {
            "agent-id": "ag0VYyLh0YTsymdbtYIaaaa",
            "agent-status": 1,
            "name": "Ilya Workshard"
        },
        {
            "agent-id": "ag0XgxWZr7TzqWFhxboBGj1g",
            "agent-status": 1,
            "status-code-list-id": -1,
            "status-code-item-id": 1,
            "name": "Jane Smith"
        },
        {
            "agent-id": "ag1LmqEeEYRoOti9KjIi_Dng",
            "agent-status": 0,
            "name": "Paul Neverhere"
        },
        {
            "agent-id": "ag64oyEUb_Sk6bxVB9P5ye5w",
            "agent-status": 5,
            "status-code-list-id": 801,
            "status-code-item-id": 1726,
            "status-code-item-short-code": "Train",
            "name": "Padma Othertask",
            "agent-sub-status": "none"
        }
    ]
}

Get Status for single agent

To request status for an individual agent simply append the appropriate agentId /agents/agentId

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
Authorizationโœ“Basic Authentication where username is the value of username and the password is the value of Data Request TokenBasic bXljbGllbnRJZDpuZXZlcnRlbGxhbnlvbmU=

Path

NameRequiredDescriptionExample
ccPlatformโœ“Contact Center platform can be found in the url when accessing CC Configuration Manager.
North America starts NA
Europe starts EU
Canada starts CA
Asia Pacific starts AP
Australia starts AU
Bell Canada starts BC
Sandbox starts SB
na12
versionโœ“The API version. The current version is 1 resulting in. v1v1
tenantIdโœ“The CC Tenant name of the tenant to list agent status for. Tenant name is generally the same as the username above. It can be located in CC Configuration Manager @ Home :: Profile :: Tenant Nameacmecorp01
agentIdโœ“The agentId of the agent to set the status for. This can be found in CC Configuration Manager "Users" add the "Internal Id" column, or in the "General" section of the user as "Internal Id"ag64oyEUb_Sk6bxVB9P5yaaa

Single Agent Status Request

curl --location --request GET 'https://{ccPlatform}.8x8.com/api/v{version}/tenants/{tenantId}/agentstatus/agents/{agentId}' \
--header 'Authorization: Basic {encodedValue}'

Single Agent Status Response

{
  "agent-id": "ag64oyEUb_Sk6bxVB9P5yaaa",
  "agent-status": 5,
  "status-code-list-id": 801,
  "status-code-item-id": 1726,
  "status-code-item-short-code": "Train",
  "name": "Padma Othertask",
  "agent-sub-status": "none"
}

Allowed Status Transitions

  • Red lines indicate single direction (not reversible via API)
  • Black lines indicate bidirectional
  • All other transitions are NOT supported via API

Agent status API Reference allows you to try out this API.

Set Status for a single agent

The status can only be set to and from the statuses defined in allowed status change diagram

Parameters

Method: PUT

Headers

NameRequiredDescriptionExample
Authorizationโœ“Basic Authentication where username is the value of username and the password is the value of Action Request TokenBasic bXljbGllbnRJZDpuZXZlcnRlbGxhbnlvbmU=
Content-Typeโœ“Set the content type to application/jsonapplication/json

Path

NameRequiredDescriptionExample
ccPlatformโœ“Contact Center platform can be found in the url when accessing CC Configuration Manager.
North America starts NA
Europe starts EU
Canada starts CA
Asia Pacific starts AP
Australia starts AU
Bell Canada starts BC
Sandbox starts SB
na12
versionโœ“The API version. The current version is 1 resulting in. v1v1
tenantIDโœ“The CC Tenant name of the tenant to list agent status for. Tenant name is generally the same as the username above. It can be located in CC Configuration Manager @ Home :: Profile :: Tenant Nameacmecorp01
agentIdโœ“The agentId of the agent to set the status for. This can be found in CC Configuration Manager "Users" add the "Internal Id" column, or in the "General" section of the user as "Internal Id"ag0VYyLh0YTsymdbtYIaaaa

Body

NameRequiredDescriptionExample
agent-statusโœ“The status to assign to the agent. See Status Values5
status-code-list-idโœ“Status Code List Id is the id of the list. See Status Code Lists and Items801
status-code-item-idโœ“The id of the item within the status code list. See Status Code Lists and Items1722
status-code-item-short-codeโœ“Short Text associated to the item within the status code list. See Status Code Lists and ItemsMeet

Set Single Agent Status Request

curl --location --request PUT 'https://{ccPlatform}.8x8.com/api/v{version}/tenants/{tenantId}/agentstatus/agents/{agentId}' \
--header 'Authorization: Basic {encodedValue}'
--header 'Content-Type: application/json' \
--data-raw '{
    "agent-status": 5,
    "status-code-list-id": 801,
    "status-code-item-id": 1722,
    "status-code-item-short-code": "Meet"
}'

Set Single Agent Status Response

{
    "reason": "OK",
    "change-status": 200,
    "message": "Agent status change successful"
}

๐Ÿšง

403 response code 403 - Forbidden.

Historically this capability has only enabled on request. If you receive response code 403 then please contact 8x8 support and request that your "Agent Status API" is enabled in OPSCON.

Set Status for Agents in bulk

To set the status of multiple agents in a single request.

  • The requested status can be different for each agent.
  • Each agent request is independent and some requests can succeed and others fail within a single request. The outcome is delivered via a HTTP 207 Multi-Status response.

Parameters

Method: PUT

Headers

NameRequiredDescriptionExample
Authorizationโœ“Basic Authentication where username is the value of username and the password is the value of Action Request Token.Basic bXljbGllbnRJZDpuZXZlcnRlbGxhbnlvbmU=
Content-Typeโœ“Set the content type to application/jsonapplication/json

Path

NameRequiredDescriptionExample
ccPlatformโœ“Contact Center platform can be found in the url when accessing CC Configuration Manager.
North America starts NA
Europe starts EU
Canada starts CA
Asia Pacific starts AP
Australia starts AU
Bell Canada starts BC
Sandbox starts SB
na12
versionโœ“The API version. The current version is 1 resulting in. v1v1
tenantIdโœ“The CC Tenant name of the tenant to list agent status for. Tenant name is generally the same as the username above. It can be located in CC Configuration Manager @ Home :: Profile :: Tenant Nameacmecorp01

Body

The body will contain an array of agents, each entry in the array will have the following:

NameRequiredDescriptionExample
agents.agent-idโœ“The agentId of the agent to set the status for. This can be found in CC Configuration Manager "Users" add the "Internal Id" column, or in the "General" section of the user as "Internal Id"ag64oyEUb_Sk6bxVB9P5yaaa
agents.agent-statusThe status to assign to the agent. See Status Values5
agents.status-code-list-idโœ“Status Code List Id is the id of the list. See Status Code Lists and Items801
agents.status-code-item-idโœ“The id of the item within the status code list. See Status Code Lists and Items1722
agents.status-code-item-short-codeโœ“Short Text associated to the item within the status code list. See Status Code Lists and ItemsMeet

Set Bulk Status Request

curl --location --request PUT 'https://<<ccPlatform>>.8x8.com/api/v1/tenants/<<tenantId>>/agentstatus/agents/bulk' \
--header 'Authorization: Basic <<encodedValue>>'
--header 'Content-Type: application/json' \
--data-raw '{
    "agents": [
    {
        "agent-id": "ag64oyEUb_Sk6bxVB9P5yaaa",
        "agent-status": 3,
        "status-code-list-id": 801,
        "status-code-item-id": 1725,
        "status-code-item-short-code": "Lunch"
    },
    {
        "agent-id": "agAQDqmvKiRbG4ekigNSmbbb",
        "agent-status": 3,
        "status-code-list-id": 801,
        "status-code-item-id": 1725,
        "status-code-item-short-code": "Lunch"
    }
]
}'

Set Bulk Status Response

Response Status is 207 and the individual status of each agent status change is contained in the body of the response

{
    "data": [
        {
            "agent-id": "ag64oyEUb_Sk6bxVB9P5yaaa",
            "reason": "OK",
            "change-status": 200,
            "message": "Agent status change successful"
        },
        {
            "agent-id": "agAQDqmvKiRbG4ekigNSmbbb",
            "reason": "OK",
            "change-status": 200,
            "message": "Agent status change successful"
        }
    ]
}

References

Status Values that can be changed as explained in the diagram form the beginning of this documentation:

StatusLabelDescription
1LOGGED_OUTCurrently logged out (and has previously logged in at least one time)
3ON_BREAKOn break status, could be manually selected or automatically on break based on initial login or missing a transaction.
4WAIT_TRANSACTAvailable
5WORK_OFFLINEWorking offline

Status Values that can be returned by the GET operations but cannot be ammended by the SET operation:

StatusLabelDescription
0UNKNOWNGenerally the Agent has never logged in
2LOGGED_IN
6TRANSACT_OFFERED
7PROCESS_TRANSACT
8POST_PROCESS
9BUSY
10DIRECT_CALLNote: If a direct call is also marking the agent Busy then the status will be 9 BUSY
11ON_EMAIL

Status Code Lists and Items

Status Code Lists are assigned to Agent Groups via CC Configuration Manager.
These lists allow for a specific reason for the status to be selected by the agent or in this case assigned via the API.

status-code-list-id this is the id of the list itself: This can be identified either by using the Get Agent Status or via the stats API.

status-code-item-id this is the id of the list itself: This can be identified either by using the Get Agent Status to return the values for an agent in a known state or via the stats API.

status-code-item-short-code This can be found in CC Configuration Manager under: Status Codes, by selecting the required Status Code List, then under "Codes" referencing the "Short Codes" column, or by using the Get Agent Status to return the values for an agent in a known state or via the stats API.