Agent status endpoints

The agent status API endpoints provide access to the agent status objects. An agent object is created for each user that is configured in Contact Center AI Platform (CCAI Platform) that has a role including an agent permission.

The following are the agent status API endpoints:

Update agent statuses
Get agent statuses

Agent status endpoints let you modify the status of agents. They enable changes from Available to any custom status. Transitions to and from system-defined statuses like In-Call trigger an error. In addition, these endpoints supports bulk updates, simultaneously allowing status modifications for entire teams or selected groups of agents.

Update agent status

This endpoint lets you update the status of agents. The following table shows the properties in the JSON body:

Property	Required	Data Type	Definition
status	TRUE	String	The status to set the agents to, for example available.
agent_ids	TRUE	Arry Integer	ARRAY of agent IDs.
team_ids	TRUE	Array Integer	ARRAY of team IDs.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/agent_statuses

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "status": "Available",
    "agent_ids": [
        11,
        12
    ],
    "team_ids": []
}

Example request and responses

The following sections provide example requests to the endpoint.

Change agent statuses successfully

The following example demonstrates the request and associated response of changing some agents status where the action was successful.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "status": "Available",
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ]
}

Response:

[
    {
        "agent_id": 11,
        "name": "Darth Vader",
        "email": "notanakinskywalker@empire.com",
        "agent_number": "Agent No.111",
        "previous_status": "lunch",
        "current_status": "Available"
    },
    {
        "agent_id": 12,
        "name": "Craig T",
        "email": "craigT@nelson.com",
        "agent_number": "Agent No.112",
        "previous_status": "In-call",
        "current_status": "In-call",
        "message": "Agent can't be changed from system status 'In-call'"
    },
    {
        "agent_id": 13,
        "name": "Raymond D",
        "email": "rayd@nelson.com",
        "agent_number": "Agent No.113",
        "previous_status": "Offline",
        "current_status": "Offline",
        "message": "Agent's status can't be changed if they are offline or logged out"
    }
]

Status Code: 200

Status does not exist

This example shows the request and associated response where the provided status does not exist and as such is considered invalid.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

Body
{
    "status": "Napping",
    "agent_ids": [
        11,
        12
    ],
    "team_ids": []
}

Response: Error: status 'Napping' does not exist

{
    "message": "status 'Napping' does not exist"
}

Status Code: 400

Status set to system status

This example shows the request and response where the status is set to a system status, in this case "in-call". It is not possible to set the status of an agent to a status that is managed by the system.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

Body
{
    "status": "In-call",
    "agent_ids": [
        11,
        12
    ]
}

Response: Error: Agent can't be changed to system status 'In-call

{
    "message": "Agent can't be changed to system status 'In-call'"
}

Status Code: 400

Get agent statuses

This endpoint lets you retrieve the status of agents. The following table shows the properties in the JSON body:

Property	Required	Data Type	Definition
status	TRUE	String	The status to set the agents to, for example available.
agent_ids	FALSE	Arry Integer	ARRAY of agent IDs.
team_ids	FALSE	Array Integer	ARRAY of team IDs.

Endpoint:

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/agent_statuses

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ]
}

Example request and responses

The following sections provide example requests to the endpoint.

Get the status specific agents and teams

This example shows how to get the status of agents with IDs 11 and 12 and any agent on the team with ID 1.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ]
}

Response: Status of requested agents

[
    {
        "agent_id": 11,
        "name": "Darth Vader",
        "email": "notanakinskywalker@empire.com",
        "agent_number": "Agent No.111",
        "status": "lunch",
        "ip_addrs": [
            "34.211.11.101"
        ]
    },
    {
        "agent_id": 12,
        "name": "Craig T",
        "email": "craigT@nelson.com",
        "agent_number": "Agent No.112",
        "status": "In-call",
        "ip_addrs": [
            "34.211.11.102"
        ]
    },
    {
        "agent_id": 13,
        "name": "Raymond D",
        "email": "rayd@nelson.com",
        "agent_number": "Agent No.113",
        "status": "Offline",
        "ip_addrs": [
            "34.211.11.103"
        ]
    }
]

Status Code: 200