Retrieve Users - CometChat Docs

AI Integration Quick Reference

Field	Value
Package	`@cometchat/chat-sdk-javascript`
Import	`import { CometChat } from "@cometchat/chat-sdk-javascript";`
Key methods	`usersRequest.fetchNext()` (build via `UsersRequestBuilder`) · `CometChat.getLoggedinUser()` · `CometChat.getUser(uid)` · `CometChat.getOnlineUserCount()`
Request builder	`CometChat.UsersRequestBuilder` — configure with `.setLimit()` · `.setSearchKeyword()` · `.searchIn()` · `.setStatus()` · `.hideBlockedUsers()` · `.setRoles()` · `.friendsOnly()` · `.setTags()` · `.withTags()` · `.setUIDs()` · `.sortBy()` · `.sortByOrder()`; then `.build()` → `.fetchNext()` (call repeatedly to paginate)
Key classes	`CometChat.User` (access via `getUid()`, `getName()`, `getStatus()`, `getRole()`, `getTags()`); status via `CometChat.USER_STATUS.ONLINE` / `.OFFLINE`
Primary output	`Promise<CometChat.User[]>` from `fetchNext()`; `getLoggedinUser()` / `getUser()` resolve to a single `CometChat.User`; `getOnlineUserCount()` resolves to a `number`; all reject with `CometChat.CometChatException`
Prerequisites	SDK initialized via `CometChat.init()` and a logged-in user via `CometChat.login()`
Constraints	`setUIDs()` fetches a maximum of 25 users per request; `searchIn()` defaults to both `uid` and `name`; default sort order is `status → name → UID`, ascending
Related	User Presence · Block Users · User Management · Retrieve Conversations
Full reference	`User`

Retrieve Logged In User Details

You can get the details of the logged-in user using the getLoggedInUser() method. This method can also be used to check if the user is logged in or not. If the method returns Promise with reject callback, it indicates that the user is not logged in and you need to log the user into CometChat SDK.

Get Logged In User Details

// Fetch users list
const request = new CometChat.UsersRequestBuilder()
  .setLimit(30).build();
const users = await request.fetchNext();

// Get specific user details
const user = await CometChat.getUser("UID");

// Get logged-in user
const me = await CometChat.getLoggedinUser();

// Get online user count
const count = await CometChat.getOnlineUserCount();

The CometChat SDK provides methods to retrieve the logged-in user, fetch filtered user lists, look up individual users by UID, and get online user counts. All user methods return User objects.

User Object Fields

Field	Getter	Return Type	Description
uid	`getUid()`	`string`	Unique user ID
name	`getName()`	`string`	Display name of the user
avatar	`getAvatar()`	`string`	URL of the user’s avatar image
status	`getStatus()`	`string`	Online status of the user
lastActiveAt	`getLastActiveAt()`	`number`	Timestamp when the user was last active
role	`getRole()`	`string`	Role assigned to the user

Get the Logged-In User

Use getLoggedinUser() to get the current user’s details. Resolves with null if no user is logged in.

TypeScript
JavaScript

CometChat.getLoggedinUser().then(
  (user: CometChat.User) => {
      console.log("user details:", { user });
  }, (error: CometChat.CometChatException) => {
      console.log("error getting details:", { error });
  }
);

CometChat.getLoggedinUser().then(
user => {
  console.log("user details:", { user });
}, error => {
  console.log("error getting details:", { error });
}
);

This method returns a User object with the logged-in user’s information

Retrieve List of Users

In order to fetch the list of users, you can use the UsersRequest class. To use this class i.e to create an object of the UsersRequest class, you need to use the UsersRequestBuilder class. The UsersRequestBuilder class allows you to set the parameters based on which the users are to be fetched. Fetching using this builder will return User objects The UsersRequestBuilder class allows you to set the below parameters:

Set Limit

Sets the number of users to fetch per request.

TypeScript
JavaScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .build();

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .build();

Set Search Keyword

With offline support on, this filter is answered by the server only; the cached page is empty.

Filters users by a search string.

TypeScript
JavaScript

let limit: number = 30;
let searchKeyword: string = "super";
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setSearchKeyword(searchKeyword)
  .build();

let limit = 30;
let searchKeyword = "super";
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setSearchKeyword(searchKeyword)
                  .build();

Search In

With offline support on, this filter is answered by the server only; the cached page is empty.

Specifies which user properties to search. Works with setSearchKeyword(). By default, searches both UID and name.

TypeScript
JavaScript

let limit: number = 30;
let searchKeyword: string = "super";
let searchIn: Array<String> = ["uid", "name"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setSearchKeyword(searchKeyword)
  .searchIn(searchIn)
  .build();

let limit = 30;
let searchKeyword = "super";
let searchIn = ["uid", "name"];
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setSearchKeyword(searchKeyword)
                  .searchIn(searchIn)
                  .build();

Set Status

With offline support on, this filter is answered by the server only; the cached page is empty.

Filters users by online status:

CometChat.USER_STATUS.ONLINE — Only online users
CometChat.USER_STATUS.OFFLINE — Only offline users

If not set, returns all users.

TypeScript
JavaScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setStatus(CometChat.USER_STATUS.ONLINE)
  .build(); 

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setStatus(CometChat.USER_STATUS.ONLINE)
  .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
status	`getStatus()`	`string`	Online status of the user (`"online"` or `"offline"`)

Hide Blocked Users

When true, excludes users blocked by the logged-in user from the results.

TypeScript
JavaScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .hideBlockedUsers(true)
  .build();

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .hideBlockedUsers(true)
                  .build();

Set Roles

Filters users by specified roles.

TypeScript
JavaScript

let limit: number = 30;
let roles: Array<String> = ["default", "dev"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setRoles(roles)
  .build();

let limit = 30;
let roles = ["default", "dev"];
let usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setRoles(roles)
  .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
role	`getRole()`	`string`	Role assigned to the user

Friends Only

When true, returns only friends of the logged-in user.

TypeScript
JavaScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .friendsOnly(true)
  .build();

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .friendsOnly(true)
                  .build();

Set Tags

Filters users by specified tags.

TypeScript
JavaScript

let limit: number = 30;
let tags: Array<String> = ["tag1", "tag2"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setTags(tags)
  .build();

let limit = 30; let tags = ["tag1", "tag2"]; let usersRequest =

new CometChat.UsersRequestBuilder() .setLimit(limit) .setTags(tags) .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
tags	`getTags()`	`string[]`	Tags associated with the user

With Tags

When true, includes tag data in the returned user objects.

TypeScript
JavaScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .withTags(true)
  .build();

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .withTags(true)
  .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
tags	`getTags()`	`string[]`	Tags associated with the user

Set UIDs

Fetches specific users by their UIDs. Maximum 25 users per request.

TypeScript
JavaScript

let limit: number = 30;
let UIDs: Array<String> = ["cometchat-uid-1", "cometchat-uid-2"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setUIDs(UIDs)
  .build();

let limit = 30;
let UIDs = ["cometchat-uid-1", "cometchat-uid-2"];
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setUIDs(UIDs)
                  .build();

Sort By

Sorts the user list by a specific property. Default sort order: status → name → UID. Pass "name" to sort by name → UID.

TypeScript
JavaScript

let limit: number = 30;
let sortBy: string = "name";
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .sortBy(sortBy)
  .build(); 

let limit = 30;
let UIDs = ["cometchat-uid-1", "cometchat-uid-2"];
let sortBy = "name";
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .sortBy(sortBy)
                  .build();

Sort By Order

Sets the sort order. Default is ascending ("asc"). Use "desc" for descending.

TypeScript
JavaScript

let limit: number = 30;
let sortOrder: string = "desc";
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .sortByOrder(sortOrder)
  .build();

let limit = 30;
let sortOrder = "desc";
let usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .sortByOrder(sortOrder)
  .build();

After configuring the builder, call build() to get the UsersRequest object, then call fetchNext() to retrieve users.

TypeScript
JavaScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
.setLimit(limit)
.build();

usersRequest.fetchNext().then(
(userList: CometChat.User[]) => {
console.log("User list received:", userList);
}, (error: CometChat.CometChatException) => {
console.log("User list fetching failed with error:", error);
}
);

const limit = 30;
const usersRequest = new CometChat.UsersRequestBuilder()
.setLimit(limit)
.build();

usersRequest.fetchNext().then(
userList => {
  console.log("User list received:", userList);
}, error => {
  console.log("User list fetching failed with error:", error);
}
);

The fetchNext() method returns an array of User objects.

Retrieve Particular User Details

Use getUser() to fetch a specific user’s details by UID.

TypeScript
JavaScript

let UID: string = "UID";
CometChat.getUser(UID).then(
  (user: CometChat.User) => {
      console.log("User details fetched for user:", user);
  }, (error: CometChat.CometChatException) => {
      console.log("User details fetching failed with error:", error);
  }
);

let UID = "UID";
CometChat.getUser(UID).then(
user => {
  console.log("User details fetched for user:", user);
}, error => {
  console.log("User details fetching failed with error:", error);
}
);

Parameter	Description
UID	The UID of the user to fetch

It returns the User object containing the details of the user.

Get Online User Count

Use getOnlineUserCount() to get the total number of online users in your app.

TypeScript
JavaScript

CometChat.getOnlineUserCount().then(
  (userCount: number) => {
      console.log("Total online user count:", userCount);
  }, (error: CometChat.CometChatException) => {
      console.log("Online user count fetching failed with error:", error);
  }
);

CometChat.getOnlineUserCount().then(
userCount => {
  console.log("Total online user count:", userCount);
}, error => {
  console.log("Online user count fetching failed with error:", error);
}
);

Returns the total online user count as a number.

Offline Behaviour

With offline support enabled, UsersRequest.fetchNext() accepts a UserFetchListener and first delivers onCachedUsers from the device (the pages the server last returned for this exact request, replayed on-device, empty when nothing was recorded), then onServerUsers with the live page to reconcile by uid. Offline, the read ends with onError with code FAILED_TO_FETCH after the cached page. A request that uses a server-only filter records nothing, so its cached page is always empty. See Show Cached Data.

Builder method	Offline
`setLimit()`	Cached
`setSearchKeyword()`	Server only — cached page is empty
`searchIn()`	Used only with `setSearchKeyword()`, so server only
`setStatus()`	Server only — cached page is empty
`hideBlockedUsers()`	Cached
`setRole()` / `setRoles()`	Cached
`friendsOnly()`	Cached
`setTags()`	Cached
`withTags()`	Cached
`setUIDs()`	Cached
`sortBy()`	Cached
`sortByOrder()`	Cached

Next Steps

User Presence

Track and subscribe to user online/offline status

Block Users

Block and unblock users from your application

User Management

Create, update, and delete users programmatically

Retrieve Conversations

Fetch conversation lists for your chat UI

​Retrieve Logged In User Details

​User Object Fields

​Get the Logged-In User

​Retrieve List of Users

​Set Limit

​Set Search Keyword

​Search In

​Set Status

​Hide Blocked Users

​Set Roles

​Friends Only

​Set Tags

​With Tags

​Set UIDs

​Sort By

​Sort By Order

​Retrieve Particular User Details

​Get Online User Count

​Offline Behaviour

​Next Steps

User Presence

Block Users

User Management

Retrieve Conversations

Retrieve Logged In User Details

User Object Fields

Get the Logged-In User

Retrieve List of Users

Set Limit

Set Search Keyword

Search In

Set Status

Hide Blocked Users

Set Roles

Friends Only

Set Tags

With Tags

Set UIDs

Sort By

Sort By Order

Retrieve Particular User Details

Get Online User Count

Offline Behaviour

Next Steps