Retrieve Groups

Guide to fetching group lists using the CometChat iOS SDK GroupsRequest builder with search and filtering options.

Quick Reference for AI Agents & Developers

• Build request: GroupsRequest.GroupsRequestBuilder().set(limit:).build()
• Fetch groups: groupsRequest.fetchNext(onSuccess:onError:)
• Get single group: CometChat.getGroup(GUID:onSuccess:onError:)
• Online count: CometChat.getOnlineGroupMemberCount(_:onSuccess:onError:)
• Filters: .set(searchKeyword:), .set(joinedOnly:), .set(tags:), .withTags(_:)
• Related: Create Group · Join Group · Groups Overview

Group Data Model

The Group class represents a CometChat group with all its properties.

Swift

let group = Group(guid: "group123", name: "My Group", groupType: .public, password: nil)

Group Properties

Property	Type	Description
guid	String	Unique group identifier (required)
name	String?	Group display name
groupType	GroupType	.public, .private, or .password
icon	String?	Group icon URL
groupDescription	String?	Group description
owner	String?	UID of group owner
metadata	[String: Any]?	Custom metadata dictionary
createdAt	Int	Creation Unix timestamp
updatedAt	Int	Last update Unix timestamp
hasJoined	Bool	Whether logged-in user is a member
joinedAt	Int	When user joined (Unix timestamp)
membersCount	Int	Total number of members
scope	MemberScope	User’s scope in group
tags	[String]	Array of group tags
password	String?	Password (for password-protected groups)

Sample Payload - Group Object

Group Object Properties:

Parameter	Type	Description
guid	String	Unique group identifier. Example: "cometchat-guid-1"
name	String?	Group display name. Example: "Hiking Group"
groupType	GroupType	Type of group. Example: .public
icon	String?	URL to the group’s icon image. Example: "https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp"
groupDescription	String?	Description of the group. Example: "Explore, connect, and chat with fellow outdoor enthusiasts"
owner	String?	UID of the group owner. Example: "cometchat-uid-5"
membersCount	Int	Total number of members in the group. Example: 5
hasJoined	Bool	Whether the logged-in user is a member. Example: true
joinedAt	Int	Unix timestamp when user joined. Example: 1753861429
scope	MemberScope	User’s scope in the group. Example: .participant
createdAt	Int	Unix timestamp when group was created. Example: 1753861429
updatedAt	Int	Unix timestamp of last update. Example: 0
tags	[String]	Array of tags associated with the group. Example: ["general", "public"]
metadata	[String: Any]?	Custom metadata dictionary. Example: ["category": "social", "isVerified": true]

Metadata Properties (when present):

Parameter	Type	Description
metadata.category	String	Category of the group. Example: "social"
metadata.isVerified	Bool	Whether the group is verified. Example: true

---

Retrieve List of Groups

In other words, as a logged-in user, how do I retrieve the list of groups I’ve joined and groups that are available?

In order to fetch the list of groups, you can use the GroupsRequest class. To use this class i.e to create an object of the GroupsRequest class, you need to use the GroupsRequestBuilder class. The GroupsRequestBuilder class allows you to set the parameters based on which the groups are to be fetched.

GroupsRequestBuilder Methods

Method	Parameter	Returns	Description
init(limit:)	Int	GroupsRequestBuilder	Constructor with limit
set(limit:)	Int	GroupsRequestBuilder	Number of groups to fetch (1-100)
set(searchKeyword:)	String	GroupsRequestBuilder	Search in group name
set(joinedOnly:)	Bool	GroupsRequestBuilder	Only joined groups
set(tags:)	[String]	GroupsRequestBuilder	Filter by group tags
withTags(_:)	Bool	GroupsRequestBuilder	Include tags in response
build()	-	GroupsRequest	Build the request object

Sample Payload - GroupsRequestBuilder

Builder Configuration:

Parameter	Type	Description
limit	Int	Maximum number of groups to fetch per request. Range: 1-100. Example: 30
searchKeyword	String	Search string to filter groups by name. Example: "team"
joinedOnly	Bool	Whether to return only groups the user has joined. Example: true
tags	[String]	Filter groups by tags. Example: ["premium", "verified"]
withTags	Bool	Include tags data in response. Example: true

Common Filter Combinations:

Use Case	Builder Configuration
Fetch all groups	.set(limit: 30).build()
Fetch only joined groups	.set(limit: 30).set(joinedOnly: true).build()
Search groups by name	.set(limit: 30).set(searchKeyword: "team").build()
Fetch groups with specific tags	.set(limit: 30).set(tags: ["premium", "verified"]).build()
Fetch groups with tags data	.set(limit: 30).withTags(true).build()
Combined filters	.set(limit: 30).set(joinedOnly: true).set(searchKeyword: "project").withTags(true).build()

• fetchNext() returns public and password groups by default
• Private groups only returned if user is a member
• Use set(joinedOnly: true) to get only groups user has joined

Set Limit

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

Swift

let groupsRequest = GroupsRequest.GroupsRequestBuilder()
    .set(limit: 30)
    .build()

Set Search Keyword

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

Swift

let groupsRequest = GroupsRequest.GroupsRequestBuilder()
    .set(searchKeyword: "abc")
    .set(limit: 30)
    .build()

Joined Only

This method when used, will ask the SDK to only return the groups that the user has joined or is a part of.

Swift

let groupsRequest = GroupsRequest.GroupsRequestBuilder()
    .set(joinedOnly: true)
    .set(limit: 30)
    .build()

Set Tags

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

Swift

let groupsRequest = GroupsRequest.GroupsRequestBuilder()
    .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 groups.

Swift

let groupsRequest = GroupsRequest.GroupsRequestBuilder()
    .set(limit: 30)
    .withTags(true)
    .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 GroupsRequest class.

Once you have the object of the GroupsRequest class, you need to call the fetchNext() method. Calling this method will return a list of Group objects containing n number of groups where n is the limit set in the builder class.

The list of groups fetched will only have the public and password type groups. The private groups will only be available if the user is a member of the group.

Swift

let limit = 30

let groupsRequest = GroupsRequest.GroupsRequestBuilder(limit: limit).build()

groupsRequest.fetchNext(onSuccess: { (groups) in
    for group in groups {
        print("Group: \(group.stringValue())")
    }
}, onError: { (error) in
    print("Error: \(error?.errorDescription)")
})

Objective C

NSInteger limit = 30;

GroupsRequest *groupRequest = [[[GroupsRequestBuilder alloc]initWithLimit:limit] build];

[groupRequest fetchNextOnSuccess:^(NSArray<Group *> * groups) {
    for (Group *group in groups) {
        NSLog(@"Group: %@", [group stringValue]);
    }
} onError:^(CometChatException * error) {
    NSLog(@"Error: %@", [error errorDescription]);
}];

Sample Payload - Fetch Groups

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of groups to fetch. Example: 30

Success Response (Array of Group Objects):

Parameter	Type	Description
guid	String	Unique group identifier. Example: "_dbhbcdsh_b211ad"
name	String?	Group display name. Example: "Dbhbcdsh"
groupType	GroupType	Type of group. Example: .public
icon	String?	URL to the group’s icon image. Example: nil
groupDescription	String?	Description of the group. Example: nil
owner	String?	UID of the group owner. Example: "sanket"
membersCount	Int	Total number of members. Example: 9
hasJoined	Bool	Whether the logged-in user is a member. Example: true
joinedAt	Int	Unix timestamp when user joined. Example: 1753861429
scope	MemberScope	User’s scope in the group. Example: .participant
createdAt	Int	Unix timestamp when group was created. Example: 1753861429
tags	[String]	Array of tags. Example: []
metadata	[String: Any]?	Custom metadata dictionary. Example: [:]

Response Summary:

Parameter	Type	Description
type	String	Response type. Example: "[Group]"
count	Int	Number of groups returned. Example: 30

Sample Group Entries:

guid	name	groupType	membersCount	hasJoined	scope	owner
_dbhbcdsh_b211ad	Dbhbcdsh	.public	9	true	.participant	sanket
09f095a4-02e4-4097-9c1c-3df2620f61ff	Bcvdsghc	.public	4	true	.participant	cometchat-uid-5
18f0078c-0f10-4fd5-9331-1a7676c8bcb2	Bros	.public	8	true	.participant	cometchat-uid-5
1ba8a356-dde5-4b09-aa36-24b5457e9274	Bc dagh c	.public	3	true	.participant	cometchat-uid-5

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: "ERR_NOT_LOGGED_IN"
errorDescription	String	Human-readable error message. Example: "User is not logged in"

Sample Payload - Fetch Joined Groups Only

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of groups to fetch. Example: 30
joinedOnly	Bool	Filter to only joined groups. Example: true

Success Response (Array of Group Objects):

Parameter	Type	Description
guid	String	Unique group identifier. Example: "_dbhbcdsh_b211ad"
name	String?	Group display name. Example: "Dbhbcdsh"
groupType	GroupType	Type of group. Example: .public
icon	String?	URL to the group’s icon image. Example: nil
owner	String?	UID of the group owner. Example: "sanket"
membersCount	Int	Total number of members. Example: 9
hasJoined	Bool	Always true for joined groups filter. Example: true
scope	MemberScope	User’s scope in the group. Example: .participant
tags	[String]	Array of tags. Example: []

Response Summary:

Parameter	Type	Description
type	String	Response type. Example: "[Group]"
count	Int	Number of joined groups returned. Example: 30
filter	String	Applied filter. Example: "joinedOnly = true"

Sample Payload - Fetch Groups with Tags Data

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of groups to fetch. Example: 30
withTags	Bool	Include tags data in response. Example: true

Success Response (Array of Group Objects):

Parameter	Type	Description
guid	String	Unique group identifier. Example: "_dbhbcdsh_b211ad"
name	String?	Group display name. Example: "Dbhbcdsh"
groupType	GroupType	Type of group. Example: .public
membersCount	Int	Total number of members. Example: 9
hasJoined	Bool	Whether the logged-in user is a member. Example: true
scope	MemberScope	User’s scope in the group. Example: .participant
owner	String?	UID of the group owner. Example: "sanket"
tags	[String]	Array of tags (populated when withTags is true). Example: ["premium", "verified"]

Response Summary:

Parameter	Type	Description
type	String	Response type. Example: "[Group]"
count	Int	Number of groups returned. Example: 30
filter	String	Applied filter. Example: "withTags = true"

Sample Payload - Fetch Groups with Search

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of groups to fetch. Example: 30
searchKeyword	String	Search string to filter groups. Example: "Cometchat-guid-1"

Success Response (Array of Group Objects):

Parameter	Type	Description
guid	String	Unique group identifier. Example: "cometchat-guid-1"
name	String?	Group display name. Example: "Hiking Group"
groupType	GroupType	Type of group. Example: .private
icon	String?	URL to the group’s icon image. Example: "https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp"
groupDescription	String?	Description of the group. Example: "Explore, connect, and chat with fellow outdoor enthusiasts"
owner	String?	UID of the group owner. Example: "cometchat-uid-5"
membersCount	Int	Total number of members. Example: 5
hasJoined	Bool	Whether the logged-in user is a member. Example: true
scope	MemberScope	User’s scope in the group. Example: .participant
tags	[String]	Array of tags. Example: []

Response Summary:

Parameter	Type	Description
type	String	Response type. Example: "[Group]"
count	Int	Number of groups matching search. Example: 1
filter	String	Applied filter. Example: "searchKeyword = Cometchat-guid-1"

---

Retrieve Particular Group Details

In other words, as a logged-in user, how do I retrieve information for a specific group?

To get the information of a group, you can use the getGroup() method.

Swift

let guid = "cometchat-guid-1"

CometChat.getGroup(GUID: guid, onSuccess: { (group) in
    print("Group: \(group.stringValue())")
}, onError: { (error) in
    print("Error: \(error?.errorDescription)")
})

Objective C

NSString *guid = @"cometchat-guid-1";

[CometChat getGroupWithGUID:guid onSuccess:^(Group * group) {
    NSLog(@"Group: %@", [group stringValue]);
} onError:^(CometChatException * error) {
    NSLog(@"Error: %@", [error errorDescription]);
}];

Parameter	Description
GUID	The GUID of the group for whom the details are to be fetched.

On success, the Group object containing the details of the group is returned.

Sample Payload - Get Group

Request Parameters:

Parameter	Type	Description
GUID	String	Unique identifier of the group to fetch. Example: "cometchat-guid-1"

Success Response (Group Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: "cometchat-guid-1"
name	String?	Group display name. Example: "Hiking Group"
groupType	GroupType	Type of group. Example: .private
icon	String?	URL to the group’s icon image. Example: "https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp"
groupDescription	String?	Description of the group. Example: "Explore, connect, and chat with fellow outdoor enthusiasts, thanks to our CometChat-enabled community platform."
owner	String?	UID of the group owner. Example: "cometchat-uid-5"
membersCount	Int	Total number of members. Example: 5
hasJoined	Bool	Whether the logged-in user is a member. Example: true
joinedAt	Int	Unix timestamp when user joined. Example: 1753861429
scope	MemberScope	User’s scope in the group. Example: .participant
createdAt	Int	Unix timestamp when group was created. Example: 1753861429
updatedAt	Int	Unix timestamp of last update. Example: 0
tags	[String]	Array of tags. Example: []
metadata	[String: Any]?	Custom metadata dictionary. Example: [:]

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: "ERR_GUID_NOT_FOUND"
errorDescription	String	Human-readable error message. Example: "Group with specified GUID does not exist"

---

Get Online Group Member Count

To get the total count of online users in particular groups, you can use the getOnlineGroupMemberCount() method.

Swift

let guids = ["cometchat-guid-1", "cometchat-guid-2"]

CometChat.getOnlineGroupMemberCount(guids, onSuccess: { countData in
    // countData: [String: Int] - GUID as key, count as value
    for (guid, count) in countData {
        print("Group \(guid): \(count) online members")
    }
}, onError: { error in
    print("Error: \(error?.errorDescription)")
})

This method returns a [String: Int] dictionary with the GUID as the key and the online member count for that group as the value.

Sample Payload - Get Online Group Member Count

Request Parameters:

Parameter	Type	Description
GUIDs	[String]	Array of group GUIDs to check. Example: ["cometchat-guid-1"]

Success Response ([String: Int] Dictionary):

Parameter	Type	Description
Int	Key is the GUID, value is the online member count. Example: "cometchat-guid-1": 0

Response Format:

GUID	Online Members
cometchat-guid-1	0
cometchat-guid-2	5
cometchat-guid-3	12

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code. Example: "ERR_NOT_LOGGED_IN"
errorDescription	String	Human-readable error message. Example: "User is not logged in"

---

GroupType Enum

Value	Description
.public	Anyone can join without approval
.private	Requires invitation or approval to join
.password	Requires password to join

MemberScope Enum

Value	Description
.admin	Full control over group
.moderator	Can manage members and messages
.participant	Regular member with basic permissions

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Login first using CometChat.login()
ERR_GUID_NOT_FOUND	Group with specified GUID does not exist	Verify the GUID is correct
ERR_INVALID_LIMIT	Invalid limit value provided	Use a limit between 1-100
ERR_ALREADY_JOINED	User is already a member of the group	Check membership before joining
ERR_NOT_A_MEMBER	User is not a member of the group	Join the group first