Force agent logout endpoints

The force logout agents endpoint let you forcibly log out online agents. Agents engaged in active calls or chats are logged out automatically when they complete their current interactions. Idle agents are logged out immediately. This endpoint supports forced logouts of specific agents, entire teams, or agents identified by IP addresses with CIDR notation, a list of IPv4/IPv6 addresses, or IP ranges. For a large number of agents, a background job is created to manage the logout process efficiently.

The following are the force agent logout API endpoints:

Force logout agents
Force logout agent jobs

Force logout agents

This endpoint provides the ability for the logout of specific agents. Agents can be identified by the following:

agent ID.
team ID.
IP address.

Endpoint:

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

Headers:

Key	Value	Description
Content-Type	application/json
Accept	application/json

Body:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ],
    "ip_addrs": [
        "34.211.11.0/24"
    ]
}

Example request and responses

The following sections provide example requests to the endpoint.

Logout agents successfully

This example demonstrates how to log out specific agents based on the agent ID and team ID. In this case they were agent IDs 11 and 12 as well as team ID 1.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "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": "Offline"
    },
    {
        "agent_id": 12,
        "name": "Craig T",
        "email": "craigT@nelson.com",
        "agent_number": "Agent No.112",
        "previous_status": "Unavailable",
        "current_status": "Offline"
    },
    {
        "agent_id": 13,
        "name": "Raymond D",
        "email": "rayd@nelson.com",
        "agent_number": "Agent No.113",
        "previous_status": "Break",
        "current_status": "Offline"
    }
]

Status Code: 200

Logout agents using IP address successfully

This example demonstrates how to logout agents by specifying an IP address range. In this case the provided IP address range is 34.211.11.0/24.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ],
    "ip_addrs": [
        "34.211.11.0/24"
    ]
}

Status Code: 200

Logout agent job created

This example demonstrates how to request the agent logouts and the resultant job that is created.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ],
    "ip_addrs": [
        "34.211.11.0/24"
    ]
}

Response

{
    "ip_addrs": [
        "34.211.11.0/16"
    ]
}

Status Code: 200

In-call or in-chat agents will log out later

This example demonstrates how agents that are in a call or in a chat will be logged out later, after the chat or call is ended.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

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

Response

[
    {
        "agent_id": 11,
        "name": "Darth Vader",
        "email": "notanakinskywalker@empire.com",
        "agent_number": "Agent No.111",
        "previous_status": "In-call",
        "current_status": "In-call",
        "message": "will force logout as soon as the ongoing call/chat is completed"
    },
    {
        "agent_id": 12,
        "name": "Craig T",
        "email": "craigT@nelson.com",
        "agent_number": "Agent No.112",
        "previous_status": "In-chat",
        "current_status": "In-chat",
        "message": "will force logout as soon as the ongoing call/chat is completed"
    }
]

Status Code: 400

Error: cannot find agents

This example demonstrates the failure scenario where the provided agents couldn't be found.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "ip_addrs": [
        "34.211.11.0/24"
    ]
}

Response: Error : cannot find any agent by input params

{
    "message": "cannot find any agent by input params"
}

Status Code: 400

Force agent logout jobs

This endpoint lets you get the status of forced logout request for an agent.

{
    "identifier": "string",
    "email": "string",
    "name": "string",
    "phone": "string"
}

Endpoint:

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

Headers:

Key	Value	Description
id		The job ID of a submitted forced logout request.

Example request and responses

The following sections provide example requests to the endpoint.

Successfully completed

This example demonstrates how to retrieve a job that has been completed successfully.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Query:

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

Response

{
    "id": 105,
    "status": "completed"
}

Status Code: 200