Retrieve Users - CometChat Docs

Quick Reference for AI Agents & Developers

Get logged-in user: CometChat.getLoggedInUser()
Get specific user: CometChat.getUser(UID:onSuccess:onError:)
Build request: UsersRequest.UsersRequestBuilder().set(limit:).build()
Fetch users: usersRequest.fetchNext(onSuccess:onError:)
Filters: .set(searchKeyword:), .set(status:), .set(roles:), .set(tags:)
Related: User Management · Block Users · Users Overview

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 nil, it indicates that the user is not logged in and you need to log the user into CometChat SDK.

Swift
Objective C

let user = CometChat.getLoggedInUser();

User *user = [CometChat getLoggedInUser];

This method will return a User object containing all the information related to the logged-in user.

Sample Payload

Success Response (User Object):

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"cometchat-uid-2"`
name	String?	Display name of the user. Example: `"George Alan"`
avatar	String?	URL to the user’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user for access control. Example: `"moderator"`
status	UserStatus	Current online status of the user. Example: `.online`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1772088145.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary for additional user info. Example: `[:]`

Returns nil if no user is logged in. Use this to check login state.

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.

UsersRequestBuilder Methods

Method	Type	Description
`set(limit:)`	Int	Number of users to fetch per request (1-100)
`set(searchKeyword:)`	String	Search string to filter users
`searchIn(_:)`	[String]	Properties to search in: “uid”, “name”
`set(status:)`	UserStatus	Filter by `.online` or `.offline`
`hideBlockedUsers(_:)`	Bool	Exclude blocked users from results
`set(roles:)`	[String]	Filter by user roles
`friendsOnly(_:)`	Bool	Return only friends
`set(tags:)`	[String]	Filter by user tags
`withTags(_:)`	Bool	Include tags in response
`setUIDs(_:)`	[String]	Fetch specific users by UID (max 25)
`sortBy(_:)`	String	Sort by property: “name”, “status”
`sortOrder(_:)`	SortOrder	`.asc` or `.desc`

Sample Payload - UsersRequestBuilder

Builder Configuration:

Parameter	Type	Description
limit	Int	Maximum number of users to fetch per request. Range: 1-100. Example: `30`
searchKeyword	String	Search string to filter users by UID or name. Example: `"john"`
searchIn	[String]	Properties to search in. Example: `["uid", "name"]`
status	UserStatus	Filter by online status. Example: `.online` or `.offline`
hideBlockedUsers	Bool	Whether to exclude blocked users from results. Example: `true`
roles	[String]	Filter users by their assigned roles. Example: `["admin", "moderator"]`
friendsOnly	Bool	Return only users who are friends. Example: `true`
tags	[String]	Filter users by tags. Example: `["premium", "verified"]`
withTags	Bool	Include tags data in response. Example: `true`
UIDs	[String]	Fetch specific users by UID (max 25). Example: `["user1", "user2"]`
sortBy	String	Property to sort by. Example: `"name"`
sortOrder	SortOrder	Sort direction. Example: `.asc` or `.desc`

Search In Values:

Value	Description
”uid”	Search in user UID field
”name”	Search in user display name field
[“uid”, “name”]	Search in both UID and name (default)

Sort Order:

Sort Pattern	Description
status => name => UID	Default sorting order when no sortBy specified
name => UID	Sorting order when sortBy is “name”

Common Filter Combinations:

Use Case	Builder Configuration
Fetch online users only	`.set(status: .online).set(limit: 30)`
Search users by name	`.set(searchKeyword: "john").searchIn(["name"])`
Fetch friends only, sorted	`.friendsOnly(true).sortBy("name").sortOrder(.asc)`
Fetch users with tags	`.set(tags: ["premium", "verified"]).withTags(true)`
Fetch specific users	`.setUIDs(["user1", "user2", "user3"])`

Set Limit

This method sets the limit i.e. the number of users that should be fetched in a single iteration.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.build()

Set Search Keyword

This method allows you to set the search string based on which the users are to be fetched.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.set(searchKeyword: "abc")
.build()

Search In

This method allows you to define in which user property should the searchKeyword be searched. This method only works in combination with setSearchKeyword(). By default the keyword is searched in both UID & Name.

Swift

let searchKeyword = "super"
let searchIn = ["uid", "name"]
let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.set(searchKeyword: searchKeyword)
.searchIn(searchIn)
.build()

Search In Values:

Value	Description
”uid”	Search in user UID
”name”	Search in user name
[“uid”, “name”]	Search in both (default)

Set Status

The status based on which the users are to be fetched. The status parameter can contain one of the below two values:

CometChat.UserStatus.online - will return the list of only online users.
CometChat.UserStatus.offline - will return the list of only offline users.

If this parameter is not set, will return all the available users.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.set(status: .online)
.build()

Hide Blocked Users

This method is used to determine if the blocked users should be returned as a part of the user list. if set to true, the user list will not contain the users blocked by the logged-in user.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.hideBlockedUsers(true)
.build()

Set Roles

This method allows you to fetch the users based on multiple roles.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.set(roles : ["role1","role2"])
.build()

Friends Only

This property when set to true will return only the friends of the logged-in user.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.friendsOnly(true)
.build();

Set Tags

This method accepts a list of tags based on which the list of users is to be fetched. The list fetched will only contain the users that have been tagged with the specified tags.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.set(tags: ["tag1", "tag2"])
.build();

With Tags

This property when set to true will fetch tags data along with the list of users.

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: 30)
.withTags(true)
.build()

Set UIDs

This method accepts a list of UIDs based on which the list of users is fetched. A maximum of 25 users can be fetched.

Swift

let UIDs = ["cometchat-uid-1", "cometchat-uid-2"]
let limit = 30
let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: limit)
.setUIDs(UIDs)
.build();

Sort By

This method allows you to sort the User List by a specific property of User. By default the User List is sorted by status => name => UID . If name is pass to the sortBy() method the user list will be sorted by name => UID.

Swift

let sortBy = "name"
let limit = 30
let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: limit)
.sortBy(sortBy)
.build();

Sort Order:

Default Sort	Description
status => name => UID	Default sorting order
name => UID	When sortBy is “name”

Sort By Order

This method allows you to sort the User List in a specific order. By default the user list is sorted in ascending order.

Swift

let limit = 30
let usersRequest = UsersRequest.UsersRequestBuilder()
.set(limit: limit)
.sortOrder(.desc)
.build();

Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the UsersRequest class. Once you have the object of the UsersRequest class, you need to call the fetchNext() method. Calling this method will return a list of User objects containing n number of users where n is the limit set in the builder class.

Swift
Objective C

let limit = 20;

let usersRequest = UsersRequest.UsersRequestBuilder(limit: limit).build();

usersRequest.fetchNext(onSuccess: { (users) in

  for user in users {

     print("User: " + user.stringValue())
  }

}) { (error) in

  print("User list fetching failed with error: " + error!.errorDescription);
}

NSInteger limit = 30 ;

UsersRequest *userRequest = [[[UsersRequestBuilder alloc]initWithLimit:limit] build];

[userRequest fetchNextOnSuccess:^(NSArray<User *> * users) {
    
    for (User *user in users) {

      NSLog(@"User: %@ ",[user stringValue]);
    }
    
} onError:^(CometChatException * error) {
    
    NSLog(@"User list fetching failed with error: %@",[error errorDescription]);
    
}];

Sample Payload

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of users to fetch in this request. Example: `30`

Success Response (Array of User Objects):

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"cometchat-uid-1"`
name	String?	Display name of the user. Example: `"Andrew Joseph"`
avatar	String?	URL to the user’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user for access control. Example: `"admin"`
status	UserStatus	Current online status of the user. Example: `.offline`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1772017498.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary for additional user info. Example: `[:]`

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code identifying the error type. Example: `"ERR_INVALID_LIMIT"`
errorDescription	String	Human-readable description of the error. Example: `"Invalid limit value provided"`

Retrieve Particular User Details

To get the information of a user, you can use the getUser() method.

Swift
Objective C

let uid  = "cometchat-uid-1";

CometChat.getUser(UID: uid, onSuccess: { (user) in

  print("User: " + user.stringValue())

}) { (error) in

  print("User fetching failed with error: " + error.errorDescription);
}

NSString *UID = @"cometchat-uid-1";

[CometChat getUserWithUID:UID onSuccess:^(User * user) {
    
    NSLog(@"User: %@",[user stringValue]);
    
} onError:^(CometChatException * error) {
    
    NSLog(@"User fetching failed with error: %@",[error errorDescription]);
}];

The getUser() method takes the following parameters:

Parameter	Description
UID	The `UID` of the user for whom the details are to be fetched.

Sample Payload

Request Parameters:

Parameter	Type	Description
UID	String	Unique identifier of the user to fetch. Example: `"cometchat-uid-2"`

Success Response (User Object):

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"cometchat-uid-2"`
name	String?	Display name of the user. Example: `"George Alan"`
avatar	String?	URL to the user’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user for access control. Example: `"moderator"`
status	UserStatus	Current online status of the user. Example: `.online`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1772104307.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary for additional user info. Example: `[:]`

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code identifying the error type. Example: `"ERR_UID_NOT_FOUND"`
errorDescription	String	Human-readable description of the error. Example: `"User with the specified UID does not exist"`

User Object

The User object represents a CometChat user with all their profile information. See Users Overview for complete details.

Parameter	Type	Description
uid	String?	Unique identifier of the user (required, not editable after creation)
name	String?	Display name of the user (required)
avatar	String?	URL to the user’s avatar image
link	String?	URL to the user’s profile page
role	String?	Role assigned to the user for access control
status	UserStatus	Current online status: `.online` or `.offline`
statusMessage	String?	Custom status message set by the user
lastActiveAt	Double	Unix timestamp of the user’s last activity
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user
blockedByMe	Bool	Indicates if the logged-in user has blocked this user
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active)
tags	[String]	Array of tags associated with the user
metadata	[String: Any]?	Custom metadata dictionary for additional user info

UserStatus Enum

Value	Raw Value	Description
.online	0	User is currently online and active
.offline	1	User is currently offline

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Login first using `CometChat.login()`
ERR_UID_NOT_FOUND	User with specified UID does not exist	Verify the UID is correct
ERR_INVALID_LIMIT	Invalid limit value provided	Use a limit between 1-100

​Retrieve Logged In User Details

​Retrieve List of Users

​UsersRequestBuilder Methods

​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

​User Object

​UserStatus Enum

​Common Error Codes

Retrieve Logged In User Details

Retrieve List of Users

UsersRequestBuilder Methods

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

User Object

UserStatus Enum

Common Error Codes