Querying Users

Last Edit: Jul 07 2020

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:


const response = await client.queryUsers({ id: { $in: ['john', 'jack', 'jessie'] } });
                    

List<String> userIds = new ArrayList();
userIds.add("john");
userIds.add("jack");
userIds.add("jessie");
FilterObject filter = Filters.in("id", userIds);
int offset = 0;
int limit = 10;
QuerySort sort = new QuerySort();

QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit, sort, false);

client.queryUsers(request).enqueue(channelResult -> Unit.INSTANCE);
                    

Client.shared.queryUsers(filter: .in("id", ["john", "jack", "jessie"])) { (result) in
   // handle result
}
                    

val filter = Filters.`in`("id", listOf("john", "jack", "jessie"))
val offset = 0
val limit = 10
val request = QueryUsersRequest(filter, offset, limit)

client.queryUsers(request).enqueue {
    val users = it.data()
}
                    

$response = $client->queryUsers([ 'id' => ['$in' => ['john', 'jack', 'jessie'] ] ]);
                    

const response = await client.queryUsers(
    { id: { $in: ['jessica'] } },
    { last_active: -1},
    { presence: true },
);
                    

List<String> userIds = new ArrayList();
userIds.add("jessica");
FilterObject filter = Filters.in("id", userIds);
int offset = 0;
int limit = 10;
QuerySort sort = new QuerySort().desc("last_active");

QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit, sort, false);

client.queryUsers(request).enqueue(channelResult -> Unit.INSTANCE);
                    

// Create a user query.
let query = UsersQuery(filter: .in("id", ["john", "jack", "jessie"]),
                       sorting: [.init("last_message_at", isAscending: false)],
                       options: .presence)

Client.shared.queryUsers(query: query) { (result) in
    // handle result
}
                    

val filter = Filters.`in`("id", listOf("jessica"))
val offset = 0
val limit = 10
val sort = QuerySort().desc("last_active")

val request = QueryUsersRequest(filter, offset, limit, sort)

client.queryUsers(request).enqueue {
    val users = it.data()
}
                    

$response = $client->queryUsers( 
[ 
  'id' => ['$in' => ['john', 'jack', 'jessie'] ],
  'last_active' => '2019-11-05T21:35:24.397995Z',
]);
                    

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


const banned = await client.queryUsers({ id: 'jessica', banned: true });
                    

$banned = $client->queryUsers( 
[ 
  'id' => 'bob-1',
  'banned' => true,
]);
                    

Client.shared.queryUsers(filter: .equal("banned", to: false)) { (result) in
   // handle result
}
                    

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.

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.

The options for the queryUser method are 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.

Name Type Description Default Optional
presence boolean Get updates when the user goes offline/online false
limit integer Number of users to return 30
offset integer Offset for pagination 0
You can subscribe to presence status of at most 30 users using this method.

Querying Using the $autocomplete Operator

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

1. By Name

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


const response = await serverClient.queryUsers({ name: { $autocomplete: 'ro' } });
                    

$response = $client->queryUsers( 
[ 
  'name' => ['$autocomplete' => 'ro']
]);
                    

Client.shared.queryUsers(filter: .autocomplete("name", with: "ro")) { (result) in
   // handle result
}
                    

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


[
    {
        "id": "userID",
        "name": "Curiosity Rover"
    },
    {
        "id": "userID2",
        "name": "Roxy"
    },
    {
        "id": "userID3",
        "name": "Roxanne"
    }
]
                    

Here are a couple of examples of querying by either username or ID. They will also return an array of any matching users.

2. By Username

The username custom field supports search with autocomplete:


const response = await client.queryUsers({ username: { $autocomplete: 'rove' } });
                    

$response = $client->queryUsers( 
[ 
  'username' => ['$autocomplete' => 'rove']
]);
                    

Client.shared.queryUsers(filter: .autocomplete("username", with: "rove")) { (result) in
   // handle result
}
                    

3. By ID


const response = await client.queryUsers({ id: { $autocomplete: 'USER_ID' } });
                    

$response = $client->queryUsers( 
[ 
  'id' => ['$autocomplete' => 'user-id']
]);
                    

Client.shared.queryUsers(filter: .autocomplete("id", with: "ro")) { (result) in
   // handle result
}