Retrieve Users

Fetch and search users in your CometChat application

Quick Reference for AI Agents & Developers

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

// Search users
const usersRequest = new CometChat.UsersRequestBuilder()
  .setSearchKeyword("john")
  .build();

// Filter online users
const usersRequest = new CometChat.UsersRequestBuilder()
  .setStatus(CometChat.USER_STATUS.ONLINE)
  .build();

// Filter by role
const usersRequest = new CometChat.UsersRequestBuilder()
  .setRoles(["admin", "moderator"])
  .build();

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

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

// Friends only
const usersRequest = new CometChat.UsersRequestBuilder()
  .friendsOnly(true)
  .build();

Retrieve user information including the logged-in user, user lists, and individual user details.

Availability: SDK, API, UI Kits

---

Get Logged-In User

Check if a user is logged in and get their details:

JavaScript

CometChat.getLoggedinUser().then(
  (user) => {
    if (user) {
      console.log("Logged in as:", user.getName());
    } else {
      console.log("No user logged in");
    }
  },
  (error) => console.log("Error:", error)
);

TypeScript

CometChat.getLoggedinUser().then(
  (user: CometChat.User | null) => {
    if (user) {
      console.log("Logged in as:", user.getName());
    }
  },
  (error: CometChat.CometChatException) => console.log("Error:", error)
);

Async/Await

async function getLoggedInUser() {
  try {
    const user = await CometChat.getLoggedinUser();
    if (user) {
      console.log("Logged in as:", user.getName());
    } else {
      console.log("No user logged in");
    }
    return user;
  } catch (error) {
    console.log("Error:", error);
    throw error;
  }
}

---

Fetch User List

Use UsersRequestBuilder to fetch users with various filters:

JavaScript

const limit = 30;

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

usersRequest.fetchNext().then(
  (userList) => console.log("Users:", userList),
  (error) => console.log("Failed:", error)
);

TypeScript

const limit: number = 30;

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

usersRequest.fetchNext().then(
  (userList: CometChat.User[]) => console.log("Users:", userList),
  (error: CometChat.CometChatException) => console.log("Failed:", error)
);

Async/Await

async function fetchUsers(limit = 30) {
  const usersRequest = new CometChat.UsersRequestBuilder()
    .setLimit(limit)
    .build();

  try {
    const userList = await usersRequest.fetchNext();
    console.log(`Fetched ${userList.length} users`);
    return userList;
  } catch (error) {
    console.error("Failed to fetch users:", error);
    throw error;
  }
}

// Usage
const users = await fetchUsers();

Builder Options

Method	Description
setLimit(limit)	Number of users per request (max 100)
setSearchKeyword(keyword)	Search users by name or UID
searchIn(fields)	Fields to search in: ["uid", "name"]
setStatus(status)	Filter by online/offline status
hideBlockedUsers(true)	Exclude blocked users
setRoles(roles)	Filter by user roles
friendsOnly(true)	Only return friends
setTags(tags)	Filter by user tags
withTags(true)	Include tags in response
setUIDs(uids)	Fetch specific users (max 25)
sortBy(field)	Sort by field (e.g., “name”)
sortByOrder(order)	Sort order: “asc” or “desc”

---

Search Users

JavaScript

const usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .setSearchKeyword("john")
  .build();

usersRequest.fetchNext().then(
  (userList) => console.log("Search results:", userList),
  (error) => console.log("Failed:", error)
);

Async/Await

async function searchUsers(keyword) {
  const usersRequest = new CometChat.UsersRequestBuilder()
    .setLimit(30)
    .setSearchKeyword(keyword)
    .build();

  try {
    const userList = await usersRequest.fetchNext();
    console.log("Search results:", userList);
    return userList;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

Search in Specific Fields

const usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .setSearchKeyword("john")
  .searchIn(["name"])  // Only search in name, not UID
  .build();

---

Filter by Status

Get only online or offline users:

// Online users only
const onlineRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .setStatus(CometChat.USER_STATUS.ONLINE)
  .build();

// Offline users only
const offlineRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .setStatus(CometChat.USER_STATUS.OFFLINE)
  .build();

---

Filter by Role

JavaScript

const usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .setRoles(["admin", "moderator"])
  .build();

usersRequest.fetchNext().then(
  (userList) => console.log("Admins and moderators:", userList),
  (error) => console.log("Failed:", error)
);

Async/Await

async function fetchUsersByRole(roles) {
  const usersRequest = new CometChat.UsersRequestBuilder()
    .setLimit(30)
    .setRoles(roles)
    .build();

  try {
    const userList = await usersRequest.fetchNext();
    console.log("Filtered users:", userList);
    return userList;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

---

Filter by Tags

JavaScript

const usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .setTags(["premium", "verified"])
  .withTags(true)  // Include tags in response
  .build();

usersRequest.fetchNext().then(
  (userList) => {
    userList.forEach((user) => {
      console.log(user.getName(), "Tags:", user.getTags());
    });
  },
  (error) => console.log("Failed:", error)
);

Async/Await

async function fetchUsersByTags(tags) {
  const usersRequest = new CometChat.UsersRequestBuilder()
    .setLimit(30)
    .setTags(tags)
    .withTags(true)
    .build();

  try {
    const userList = await usersRequest.fetchNext();
    userList.forEach((user) => {
      console.log(user.getName(), "Tags:", user.getTags());
    });
    return userList;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

---

Get Friends Only

JavaScript

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

usersRequest.fetchNext().then(
  (friends) => console.log("Friends:", friends),
  (error) => console.log("Failed:", error)
);

Async/Await

async function fetchFriends() {
  const usersRequest = new CometChat.UsersRequestBuilder()
    .setLimit(30)
    .friendsOnly(true)
    .build();

  try {
    const friends = await usersRequest.fetchNext();
    console.log("Friends:", friends);
    return friends;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

---

Fetch Specific Users

Get users by their UIDs (max 25):

JavaScript

const usersRequest = new CometChat.UsersRequestBuilder()
  .setUIDs(["user1", "user2", "user3"])
  .build();

usersRequest.fetchNext().then(
  (userList) => console.log("Specific users:", userList),
  (error) => console.log("Failed:", error)
);

Async/Await

async function fetchSpecificUsers(uids) {
  const usersRequest = new CometChat.UsersRequestBuilder()
    .setUIDs(uids)
    .build();

  try {
    const userList = await usersRequest.fetchNext();
    console.log("Specific users:", userList);
    return userList;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

---

Get Single User

Fetch details for a specific user:

JavaScript

const UID = "user1";

CometChat.getUser(UID).then(
  (user) => {
    console.log("User:", user.getName());
    console.log("Status:", user.getStatus());
    console.log("Last Active:", user.getLastActiveAt());
  },
  (error) => console.log("Failed:", error)
);

TypeScript

const UID: string = "user1";

CometChat.getUser(UID).then(
  (user: CometChat.User) => {
    console.log("User:", user.getName());
    console.log("Status:", user.getStatus());
  },
  (error: CometChat.CometChatException) => console.log("Failed:", error)
);

Async/Await

async function getUser(uid) {
  try {
    const user = await CometChat.getUser(uid);
    console.log("User:", user.getName());
    console.log("Status:", user.getStatus());
    console.log("Last Active:", user.getLastActiveAt());
    return user;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

---

Get Online User Count

Get the total number of online users in your app:

JavaScript

CometChat.getOnlineUserCount().then(
  (count) => console.log("Online users:", count),
  (error) => console.log("Failed:", error)
);

Async/Await

async function getOnlineCount() {
  try {
    const count = await CometChat.getOnlineUserCount();
    console.log("Online users:", count);
    return count;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

---

Pagination

Use fetchNext() repeatedly to paginate through results:

class UserListManager {
  constructor() {
    this.usersRequest = new CometChat.UsersRequestBuilder()
      .setLimit(30)
      .build();
    this.users = [];
  }

  async loadMore() {
    try {
      const userList = await this.usersRequest.fetchNext();
      this.users = [...this.users, ...userList];
      return userList;
    } catch (error) {
      console.log("Failed to load users:", error);
      return [];
    }
  }

  hasMore() {
    // If last fetch returned less than limit, no more users
    return this.users.length > 0;
  }
}

// Usage
const manager = new UserListManager();
const firstPage = await manager.loadMore();
const secondPage = await manager.loadMore();

---

Hide Blocked Users

Exclude users you’ve blocked from the list:

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

---

Sorting

// Sort by name ascending
const usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .sortBy("name")
  .sortByOrder("asc")
  .build();

// Sort by name descending
const usersRequestDesc = new CometChat.UsersRequestBuilder()
  .setLimit(30)
  .sortBy("name")
  .sortByOrder("desc")
  .build();

Default sort order: status → name → UID

---

Next Steps

User Management

Create and update users

User Presence

Track online/offline status

Block Users

Block and unblock users

Groups

Work with group conversations