Retrieve Group Members

Quick Reference for AI Agents & Developers

Build request: GroupMembersRequest.GroupMembersRequestBuilder(guid:).set(limit:).build()
Fetch members: groupMembersRequest.fetchNext(onSuccess:onError:)
Filters: .set(searchKeyword:), .set(scopes:)
Member scopes: .admin, .moderator, .participant
Related: Add Members · Kick Member · Groups Overview

GroupMembersRequestBuilder

Build a request to fetch group members with various filters.

GroupMembersRequestBuilder Methods

Method	Parameter	Returns	Description
`init(guid:)`	String	GroupMembersRequestBuilder	Constructor with GUID
`set(limit:)`	Int	GroupMembersRequestBuilder	Number of members to fetch (1-100)
`set(searchKeyword:)`	String	GroupMembersRequestBuilder	Search in member name
`set(scopes:)`	[String]	GroupMembersRequestBuilder	Filter by scopes
`build()`	-	GroupMembersRequest	Build the request

Sample Payload - GroupMembersRequestBuilder

Builder Configuration:

Parameter	Type	Description
guid	String	Unique group identifier (required). Example: `"cometchat-guid-1"`
limit	Int	Maximum number of members to fetch per request. Range: 1-100. Example: `30`
searchKeyword	String	Search string to filter members by name. Example: `"john"`
scopes	[String]	Filter members by scopes. Example: `["admin", "moderator"]`

Common Filter Combinations:

Use Case	Builder Configuration
Fetch all members	`.set(limit: 30).build()`
Fetch admins only	`.set(limit: 30).set(scopes: ["admin"]).build()`
Fetch moderators only	`.set(limit: 30).set(scopes: ["moderator"]).build()`
Search members by name	`.set(limit: 30).set(searchKeyword: "john").build()`
Fetch admins and moderators	`.set(limit: 30).set(scopes: ["admin", "moderator"]).build()`

GroupMembersRequest Methods (After build())

Method	Returns	Description
`fetchNext(onSuccess:onError:)`	[GroupMember]	Fetch next batch of members

In order to fetch the list of groups members for a group, you can use the GroupMembersRequest class. To use this class i.e to create an object of the GroupMembersRequest class, you need to use the GroupMembersRequestBuilder class.

Set Limit

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

Swift

let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: "cometchat-guid-1")
    .set(limit: 30)
    .build()

Set Search Keyword

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

Swift

let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: "cometchat-guid-1")
    .set(limit: 30)
    .set(searchKeyword: "abc")
    .build()

Set Scopes

This method allows you to fetch group members based on multiple scopes.

Swift

let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: "cometchat-guid-1")
    .set(limit: 30)
    .set(scopes: ["admin", "participant"])
    .build()

Fetch Group Members

Once you have the object of the GroupMembersRequest class, you need to call the fetchNext() method. Calling this method will return a list of GroupMember objects.

Swift
Objective C

let limit = 30
let guid = "cometchat-guid-1"

let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: guid)
    .set(limit: limit)
    .build()

groupMembersRequest.fetchNext(onSuccess: { (groupMembers) in
    for member in groupMembers {
        print("Member: \(member.stringValue())")
    }
}, onError: { (error) in
    print("Error: \(error?.errorDescription)")
})

NSString *guid = @"cometchat-guid-1";
NSInteger limit = 30;

GroupMembersRequest *groupMemberRequest = [[[[GroupMembersRequestBuilder alloc]initWithGuid:guid] setLimitWithLimit:limit] build];

[groupMemberRequest fetchNextOnSuccess:^(NSArray<GroupMember *> * groupMembers) {
    for (GroupMember *member in groupMembers) {
        NSLog(@"Member: %@", [member stringValue]);
    }
} onError:^(CometChatException * error) {
    NSLog(@"Error: %@", [error errorDescription]);
}];

Sample Payload - Fetch Group Members

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"cometchat-guid-1"`
limit	Int	Maximum number of members to fetch. Example: `30`

Success Response (Array of GroupMember Objects):

Parameter	Type	Description
uid	String?	Unique identifier of the member. Example: `"cometchat-uid-1"`
name	String?	Display name of the member. Example: `"John Doe"`
avatar	String?	URL to the member’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"`
scope	MemberScope	Member’s scope in the group. Example: `.admin`
joinedAt	Double	Unix timestamp when member joined. Example: `1771586968.0`
status	UserStatus	Current online status. Example: `.online`
lastActiveAt	Double	Unix timestamp of last activity. Example: `1772105474.0`

Sample Member Entries:

uid	name	scope	joinedAt	status
cometchat-uid-2	George Alan	.admin	1771586968.0	.online
cometchat-uid-1	Andrew Joseph	.participant	1771586970.0	.offline
cometchat-uid-3	Jane Smith	.moderator	1771587000.0	.offline

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: `"ERR_GROUP_NOT_JOINED"`
errorDescription	String	Human-readable error message. Example: `"The user with UID cometchat-uid-2 is not a member of the group with GUID cometchat-guid-1. Please join the group to access it."`

Sample Payload - Fetch Members by Scope (Admin)

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"cometchat-guid-1"`
limit	Int	Maximum number of members to fetch. Example: `30`
scopes	[String]	Filter by scopes. Example: `["admin"]`

Success Response (Array of GroupMember Objects):

Parameter	Type	Description
uid	String?	Unique identifier of the admin member. Example: `"cometchat-uid-2"`
name	String?	Display name of the member. Example: `"George Alan"`
avatar	String?	URL to the member’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
scope	MemberScope	Member’s scope (filtered to admin). Example: `.admin`
joinedAt	Double	Unix timestamp when member joined. Example: `1771586968.0`
status	UserStatus	Current online status. Example: `.online`

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: `"ERR_GROUP_NOT_JOINED"`
errorDescription	String	Human-readable error message. Example: `"The user is not a member of the group"`

Sample Payload - Fetch Members by Scope (Moderator)

Request Parameters:

Parameter	Type	Description
guid	String	Unique group identifier. Example: `"cometchat-guid-1"`
limit	Int	Maximum number of members to fetch. Example: `30`
scopes	[String]	Filter by scopes. Example: `["moderator"]`

Success Response (Array of GroupMember Objects):

Parameter	Type	Description
uid	String?	Unique identifier of the moderator member. Example: `"cometchat-uid-3"`
name	String?	Display name of the member. Example: `"Jane Smith"`
avatar	String?	URL to the member’s avatar image. Example: `"https://example.com/avatar.png"`
scope	MemberScope	Member’s scope (filtered to moderator). Example: `.moderator`
joinedAt	Double	Unix timestamp when member joined. Example: `1771587000.0`
status	UserStatus	Current online status. Example: `.offline`

GroupMember Object Properties

Property	Type	Description
uid	String?	Unique identifier of the member
name	String?	Display name
avatar	String?	Avatar URL
link	String?	Profile link URL
role	String?	User role
metadata	[String: Any]?	Custom metadata
status	UserStatus	`.online` or `.offline`
statusMessage	String?	Custom status message
lastActiveAt	Double	Last active Unix timestamp
scope	MemberScope	`.admin`, `.moderator`, or `.participant`
joinedAt	Double	Unix timestamp when member joined
hasJoined	Bool	Whether user has joined the group

MemberScope Enum

Scope	Raw Value	Description
.admin	”admin”	Full group management privileges
.moderator	”moderator”	Can kick/ban members, delete messages
.participant	”participant”	Default scope, can send/receive messages

Common Error Codes

Error Code	Description	Resolution
ERR_GROUP_NOT_FOUND	Group with specified GUID does not exist	Verify the GUID is correct
ERR_GROUP_NOT_JOINED	Logged-in user is not a member of the group	Join the group first
ERR_INVALID_GUID	Invalid or empty GUID provided	Provide a valid group GUID

​GroupMembersRequestBuilder

​GroupMembersRequestBuilder Methods

​GroupMembersRequest Methods (After build())