iOS/Swift

Client SDKs

Backend SDKs

Querying Users

LAST EDIT Feb 18 2021

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: 

1
const response = await client.queryUsers({ id: { $in: ['john', 'jack', 'jessie'] } });
1
2
3
4
5
6
7
8
9
10
11
12
13
// Search users with id "john", "jack", or "jessie" 
FilterObject filter = Filters.in("id", Arrays.asList("john", "jack", "jessie")); 
int offset = 0; 
int limit = 3; 
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit); 
 
client.queryUsers(request).enqueue(result -> { 
    if (result.isSuccess()) { 
        List<User> users = result.data(); 
    } else { 
        // Handle result.error() 
    } 
});
1
2
3
4
5
6
7
8
9
10
11
12
13
let controller = chatClient.userListController( 
    query: .init(filter: .in(.id, values: ["john", "jack", "jessie"])) 
) 
 
controller.synchronize { error in 
    if let error = error { 
        // handle error 
        print(error) 
    } else { 
        // access users 
        print(controller.users) 
    } 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Search for users with id "john", "jack", or "jessie" 
val request = QueryUsersRequest( 
    filter = Filters.`in`("id", listOf("john", "jack", "jessie")), 
    offset = 0, 
    limit = 3, 
) 
 
client.queryUsers(request).enqueue { result -> 
    if (result.isSuccess) { 
        val users: List<User> = result.data() 
    } else { 
        // Handle result.error() 
    } 
}
1
$response = $client->queryUsers([ 'id' => ['$in' => ['john', 'jack', 'jessie'] ] ]);
1
2
3
4
5
6
7
final _result = client.queryUsers( 
  filter: { 
    "id": { 
      "\$in": ['john', 'jack', 'jessie'] 
    } 
  }, 
);
1
2
3
4
5
const response = await client.queryUsers( 
    { id: { $in: ['jessica'] } }, 
    { last_active: -1}, 
    { presence: true }, 
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
let controller = chatClient.userListController( 
    query: .init( 
        filter: .in(.id, values: ["john", "jack", "jessie"]), 
        sort: [.init(key: .lastActivityAt, isAscending: false)] 
    ) 
) 
 
controller.synchronize { error in 
    if let error = error { 
        // handle error 
        print(error) 
    } else { 
        // access users 
        print(controller.users) 
    } 
} 
 
 
// load more if needed 
controller.loadNextUsers(limit: 10) { error in 
    // handle error / access users 
}
1
2
3
4
5
$response = $client->queryUsers(  
[  
  'id' => ['$in' => ['john', 'jack', 'jessie'] ], 
  'last_active' => '2019-11-05T21:35:24.397995Z', 
]);
1
2
3
4
5
6
7
8
9
10
11
12
final _result = client.queryUsers( 
  filter: { 
    "id": { 
      "\$in": ['john', 'jack', 'jessie'] 
    } 
  }, 
  sort: [SortOption('last_active')], 
  pagination: PaginationParams( 
    offset: 0, 
    limit: 20, 
  ), 
);

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

1
const banned = await client.queryUsers({ id: 'jessica', banned: true });
1
2
3
4
5
$banned = $client->queryUsers(  
[  
  'id' => 'bob-1', 
  'banned' => true, 
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let controller = chatClient.userListController( 
    query: .init( 
        filter: .equal(.isBanned, to: true), 
        sort: [.init(key: .lastActivityAt, isAscending: false)] 
    ) 
) 
 
controller.synchronize { error in 
    if let error = error { 
        // handle error 
        print(error) 
    } else { 
        // access users 
        print(controller.users) 
    } 
}
1
2
3
4
5
6
7
val request = QueryUsersRequest( 
    filter = Filters.eq("banned", true), 
    offset = 0, 
    limit = 10, 
) 
 
client.queryUsers(request).enqueue { /* ... */ }
1
2
3
4
5
6
FilterObject filter = Filters.eq("banned", true); 
int offset = 0; 
int limit = 10; 
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit); 
 
client.queryUsers(request).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
8
9
10
11
final _result = client.queryUsers( 
  filter: { 
    "id": "jessie", 
    "banned": true, 
  }, 
  sort: [SortOption('last_active')], 
  pagination: PaginationParams( 
    offset: 0, 
    limit: 20, 
  ), 
);

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.

nametypedescriptiondefaultoptional
presencebooleanGet updates when the user goes offline/onlinefalse✓
limitintegerNumber of users to return30✓
offsetintegerOffset for pagination0✓
You can subscribe to presence status of at most 30 users using this method.
Note - The offset limit is set to 1000.

Querying Using the $autocomplete Operator

Copied!

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

1. By Username

Copied!

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

1
const response = await serverClient.queryUsers({ name: { $autocomplete: 'ro' } });
1
2
3
4
$response = $client->queryUsers(  
[  
  'name' => ['$autocomplete' => 'ro'] 
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
let controller = chatClient.userListController( 
    query: .init(filter: .autocomplete(.name, text: "ro")) 
) 
 
controller.synchronize { error in 
    if let error = error { 
        // handle error 
        print(error) 
    } else { 
        // access users 
        print(controller.users) 
    } 
}
1
2
3
4
5
6
FilterObject filter = Filters.autocomplete("name", "ro"); 
int offset = 0; 
int limit = 10; 
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit); 
 
client.queryUsers(request).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
val request = QueryUsersRequest( 
    filter = Filters.autocomplete("name", "ro"), 
    offset = 0, 
    limit = 10, 
) 
 
client.queryUsers(request).enqueue { /* ... */ }
1
2
3
4
5
6
7
final _result = client.queryUsers( 
  filter: { 
    "name": { 
      "\$autocomplete": "ro" 
    }, 
  }, 
);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[ 
    { 
        "id": "userID", 
        "name": "Curiosity Rover" 
    }, 
    { 
        "id": "userID2", 
        "name": "Roxy" 
    }, 
    { 
        "id": "userID3", 
        "name": "Roxanne" 
    } 
]

2. By ID

Copied!
1
const response = await client.queryUsers({ id: { $autocomplete: 'USER_ID' } });
1
2
3
4
$response = $client->queryUsers(  
[  
  'id' => ['$autocomplete' => 'user-id'] 
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
let controller = chatClient.userListController( 
    query: .init(filter: .autocomplete(.id, text: "ro")) 
) 
 
controller.synchronize { error in 
    if let error = error { 
        // handle error 
        print(error) 
    } else { 
        // access users 
        print(controller.users) 
    } 
}
1
2
3
4
5
6
FilterObject filter = Filters.autocomplete("id", "USER_ID"); 
int offset = 0; 
int limit = 10; 
QueryUsersRequest request = new QueryUsersRequest(filter, offset, limit); 
 
client.queryUsers(request).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
val request = QueryUsersRequest( 
    filter = Filters.autocomplete("id", "USER_ID"), 
    offset = 0, 
    limit = 10, 
) 
 
client.queryUsers(request).enqueue { /* ... */ }
1
2
3
4
5
6
7
final _result = client.queryUsers( 
  filter: { 
    "id": { 
      "\$autocomplete": "USER_ID" 
    }, 
  }, 
);

Querying Users Feedback

Did you find the content on this page helpful?