Retrieve Users

Fetch, filter, search, and sort users using the CometChat JavaScript SDK. Includes pagination, role-based filtering, tag support, and online user counts.

AI Integration Quick Reference

// 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();

Retrieve Logged In User Details

Use getLoggedInUser() to get the current user’s details. This method also verifies if a user is logged in — a rejected promise indicates no user is logged in.

Get Logged In User Details

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

TypeScript

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

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

The method returns a User object. Access the response data using getter methods:

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

Retrieve List of Users

Use UsersRequestBuilder to fetch users with filtering, searching, and pagination.

Set Limit

Sets the number of users to fetch per request.

Set Limit

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

TypeScript

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

Set Search Keyword

Filters users by a search string.

Set Search Keyword

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

TypeScript

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

Search In

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

JavaScript

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

TypeScript

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();

Set Status

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.

Set Status

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

TypeScript

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

Hide Blocked Users

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

Hide Blocked Users

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

TypeScript

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

Set Roles

Filters users by specified roles.

Set Roles

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

TypeScript

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

Friends Only

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

Friends Only

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

TypeScript

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

Set Tags

Filters users by specified tags.

Set Tags

let limit = 30;
let tags = ["tag1", "tag2"];
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setTags(tags)
                  .build();

TypeScript

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

With Tags

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

With Tags

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

TypeScript

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

Set UIDs

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

Set UIDs

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

TypeScript

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();

Sort By

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

JavaScript

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

TypeScript

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

Sort By Order

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

JavaScript

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

TypeScript

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

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

JavaScript

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);
}
);

TypeScript

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);
  }
);

The fetchNext() method returns an array of User objects. Access the response data using getter methods:

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

Retrieve Particular User Details

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

Retrieve Particular User's Details

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);
}
);

TypeScript

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);
  }
);

Parameter	Description
UID	The UID of the user to fetch

Returns a User object with the user’s details.

The method returns a User object. Access the response data using getter methods:

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 Online User Count

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

Get Online User Count

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

TypeScript

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);
  }
);

Returns the total online user count as a number.

---

Next Steps

User Presence

Track and subscribe to user online/offline status

Block Users

Block and unblock users from your application