Returns users filtered by activation status, whether they have logged in, user type, role, search term, or inactive reason.
When the Premium User status hiding feature is enabled, users who have hidden their status from the caller remain in the response but appear as offline, and their detailed status fields are omitted.
Permissions required:
view-d-room: View direct messages.view-outside-room: View users outside the caller's rooms whenApply_permission_view-outside-roomis enabled under Settings > General > REST API.
Changelog
| Version | Description |
|---|---|
| 8.8.0 | Added status visibility filtering. |
| 6.8.0 | Added |
The authenticated user token.
The authenticated user ID.
Number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items. Refer to the official documentation to learn more.
List of fields to order by, and in which direction. JSON object, with properties listed in desired order, with values of 1 for ascending, or -1 for descending. For example, {"value": -1, "_id": 1}. Refer to the official documentation to learn more.
Filter users based on their activation status. It can either be active or deactivated
Filter the users who have logged into their accounts for the first time.
Filter the type of users to be returned. For example, 'bot', 'user', 'app', etc.
Filter the users returned based on a list of roles.
Filter the list of users returned based on a search term
Filter the users based on the reason for inactive status. The options are: idle_too_long, deactivated, and pending_approval.
OK
{
"users": [
{
"_id": "W7MRNgkYLXKKAGNvW",
"username": "agent1",
"emails": [
{
"address": "agent1@agent.com",
"verified": false
}
],
"type": "user",
"roles": [
"user",
"livechat-agent"
],
"status": "offline",
"active": true,
"name": "Agent 1",
"lastLogin": "2024-04-24T17:47:50.485Z"
},
{
"_id": "Tf44Q5AaYDehtJLzA",
"username": "agent2",
"emails": [
{
"address": "agent2@agent.com",
"verified": false
}
],
"type": "user",
"roles": [
"user",
"livechat-agent"
],
"status": "offline",
"active": true,
"name": "Agent 2",
"lastLogin": "2024-04-29T16:38:56.809Z"
},
{
"_id": "JwATAtGzrzHYHCXFy",
"username": "agent3",
"emails": [
{
"address": "agent3@agent.com",
"verified": false
}
],
"type": "user",
"roles": [
"user",
"livechat-agent"
],
"status": "online",
"active": true,
"name": "Agent3",
"lastLogin": "2024-04-30T16:59:21.879Z"
},
{
"_id": "u6C62WdHKNk5X8Rzr",
"username": "guy",
"emails": [
{
"address": "guy@guy.com",
"verified": false
}
],
"type": "user",
"roles": [
"user"
],
"status": "offline",
"active": true,
"name": "guy"
},
{
"_id": "rocket.cat",
"name": "Rocket.Cat",
"username": "rocket.cat",
"status": "online",
"active": true,
"type": "bot",
"roles": [
"bot"
],
"avatarETag": "MEhPLkenJqs3jTJP5"
}
],
"count": 5,
"offset": 0,
"total": 5,
"success": true
}Unauthorized
{
"status": "error",
"message": "You must be logged in to do this."
}