Querying Users

LAST EDIT Nov 06 2024

The Query Users method allows you to search for users and see if they are online/offline. The example below shows how you can retrieve the details for 3 users in one API call:

Another option is to query for banned users. This can be done with the following code snippet:

An object with an array of users will be returned.

Please be aware that this query will return users banned across the entire app, not at a channel level.
All filters use a Mongoose style syntax; however, we do not run MongoDB on the backend, so you can only use a subset of queries that are normally available within Mongoose. The supported queries are described below.

You can filter and sort on the custom fields you've set for your user, the user id, and when the user was last active.

Supported queries

Copied!

The options for the queryUser method are include_deactivated_users, presence, limit, and offset. If presence is true this makes sure you receive the user.presence.changed event when a user goes online or offline.

nametypedescriptiondefaultoptional
filter_conditionsobjectsConditions to use to filter the users-
presencebooleanGet updates when the user goes offline/onlinetrue
sortobject or array of objectsThe sorting used for the users matching the filters. Sorting is based on field and direction, and multiple sorting options can be provided. Direction can be ascending (1) or descending (-1).[{created_at: -1}, {id: -1}]
limitintegerNumber of users to return30
offsetintegerOffset for pagination0
id_gtstringID-based pagination. Return IDs greater than this ID. If this is not empty, the default sort order will be [{id: -1}].-
id_gtestringID-based pagination. Return IDs greater than or equal to this ID. If this is not empty, the default sort order will be [{id: -1}].-
id_ltstringID-based pagination. Return IDs less than this ID. If this is not empty, the default sort order will be [{id: -1}].-
id_ltestringID-based pagination. Return IDs less than or equal to this ID. If this is not empty, the default sort order will be [{id: -1}].-
include_deactivated_usersbooleanInclude deactivated users in the response-
You can subscribe to presence status of at most 30 users using this method.
Note - The offset limit is set to 1000.

Filter conditions

Name

Type

Description

allowed operators

id

string

ID of the user

$eq, $gt, $gte, $lt, $lte, $in, $autocomplete

role

string

role of the user

$eq, $gt, $gte, $lt, $lte, $in

banned

boolean

users that have been banned

$eq

shadow_banned

boolean

users that have been shadow banned

$eq

created_at

string, must be formatted as an RFC3339 timestamp

created time of the user

$eq, $gt, $gte, $lt, $lte, $in

updated_at

string, must be formatted as an RFC3339 timestamp

updated time of the user

$eq, $gt, $gte, $lt, $lte, $in

last_active

string, must be formatted as an RFC3339 timestamp

time when the user was last active

$eq, $gt, $gte, $lt, $lte, $in

teams

string

teams that the user belongs to

$eq, $contains

name

string

name property of the user

$eq, $autocomplete

username

string

username property of the user

$eq, $autocomplete

Querying Using the $autocomplete Operator

Copied!

You can autocomplete the results of your user query by username and/or ID.

1. By Name

Copied!

If you want to return all users whose field 'name' has a value that includes 'ro', you could do so with the following:

This would return an array of any matching users, such as:

2. By ID

Copied!