Retrieve Groups

Fetch, filter, and search groups using the CometChat Flutter SDK. Includes pagination, tag-based filtering, joined-only groups, and online member counts.

AI Integration Quick Reference

// Retrieve groups with pagination
GroupsRequest request = (GroupsRequestBuilder()
  ..limit = 30
  ..searchKeyword = "search_term"
).build();

await request.fetchNext(
  onSuccess: (List<Group> groups) {
    for (Group group in groups) {
      debugPrint("Group: ${group.name}");
    }
  },
  onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
);

// Get a specific group by GUID
await CometChat.getGroup(
  "GROUP_ID",
  onSuccess: (Group group) => debugPrint("Group: ${group.name}"),
  onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
);

// Fetch only joined groups
GroupsRequest joinedRequest = (GroupsRequestBuilder()
  ..limit = 30
  ..joinedOnly = true
).build();

// Get online member count
CometChat.getOnlineGroupMemberCount(["GUID"],
  onSuccess: (Map<String, int> count) => debugPrint("Count: $count"),
  onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
);

Retrieve groups allows you to fetch the list of groups you’ve joined and groups that are available, as well as get details for a specific group.

Available via: SDK | REST API | UI Kits

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.

Use GroupsRequestBuilder to fetch groups with filtering, searching, and pagination.

GroupsRequestBuilder

Parameter	Type	Description
limit	int?	Maximum number of groups to fetch per request. Max 100, default 30.
searchKeyword	String?	Search string to filter groups by name.
joinedOnly	bool?	When true, returns only groups the logged-in user has joined. Default false.
tags	List<String>?	List of tags to filter groups by. Only groups with the specified tags are returned.
withTags	bool?	When true, includes tag data in the returned group objects. Default false.
setPage	int?	Fetch groups from a particular page number.

Set Limit

Sets the number of groups to fetch per request.

Dart

GroupsRequest groupsRequest =  (GroupsRequestBuilder()
  ..limit= 20
).build();

Set Search Keyword

Filters groups by a search string.

Dart

GroupsRequest groupsRequest =  (GroupsRequestBuilder()
  ..limit= 20
  ..searchKeyword = "abc"  
).build();  

Joined Only

When true, returns only groups the logged-in user has joined or is a part of.

Dart

GroupsRequest groupsRequest =  (GroupsRequestBuilder()
  ..limit= 20
  ..joinedOnly = true
).build();

Set Tags

Filters groups by specified tags. The list fetched will only contain the groups that have been tagged with the specified tags.

Dart

List<String> tags =[];
tags.add("archived");
GroupsRequest groupsRequest =  (GroupsRequestBuilder()
  ..limit= 20
   ..tags = tags
).build();

With Tags

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

Dart

GroupsRequest groupsRequest =  (GroupsRequestBuilder()
  ..limit= 20
  ..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 depending on the limit set.

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 that private group.

Dart

GroupsRequest groupsRequest =  (GroupsRequestBuilder()
  ..limit= 20
).build();

groupsRequest.fetchNext(onSuccess: (List<Group> groupList) {
    debugPrint("Fetched Group Successfully : $groupList ");
  }, onError: (CometChatException e) {
    debugPrint("Group Request failed with exception: ${e.message}");
  });

Response

On Success — A List<Group> containing the fetched groups. Each Group object has the following structure:

Group Object:

Parameter	Type	Description	Sample Value
guid	string	Unique identifier for the group	"cometchat-guid-1"
name	string	Display name of the group	"Tech Enthusiasts"
icon	string	URL of the group icon	null
description	string	Description of the group	"A group for tech lovers"
membersCount	number	Number of members in the group	12
metadata	object	Custom metadata attached to the group	{}
joinedAt	number	Epoch timestamp when the logged-in user joined the group	1745554729
hasJoined	boolean	Whether the logged-in user has joined the group	true
createdAt	number	Epoch timestamp when the group was created	1745554729
owner	string	UID of the group owner	"cometchat-uid-1"
updatedAt	number	Epoch timestamp when the group was last updated	1745554729
tags	array	List of tags associated with the group	[]
type	string	Type of the group (public, private, password)	"public"
scope	string	Scope of the logged-in user in the group	"admin"
password	string	Password for password-protected groups	null
isBannedFromGroup	boolean	Whether the logged-in user is banned from the group	false

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_CHAT_API_FAILURE"
message	string	Human-readable error message	"Failed to fetch the requested data."
details	string	Additional technical details	"An unexpected error occurred while processing the request."

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.

Dart

String GUID = "GUID";

CometChat.getGroup(GUID, onSuccess: (Group group) {
      debugPrint("Fetched Group Successfully : $group ");
    }, onError: (CometChatException e) {
      debugPrint("Group Request failed with exception: ${e.message}");
    });

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.

Response

On Success — A Group object containing all details of the requested group:

Group Object:

Parameter	Type	Description	Sample Value
guid	string	Unique identifier for the group	"cometchat-guid-1"
name	string	Display name of the group	"Tech Enthusiasts"
icon	string	URL of the group icon	null
description	string	Description of the group	"A group for tech lovers"
membersCount	number	Number of members in the group	12
metadata	object	Custom metadata attached to the group	{}
joinedAt	number	Epoch timestamp when the logged-in user joined the group	1745554729
hasJoined	boolean	Whether the logged-in user has joined the group	true
createdAt	number	Epoch timestamp when the group was created	1745554729
owner	string	UID of the group owner	"cometchat-uid-1"
updatedAt	number	Epoch timestamp when the group was last updated	1745554729
tags	array	List of tags associated with the group	[]
type	string	Type of the group (public, private, password)	"public"
scope	string	Scope of the logged-in user in the group	"admin"
password	string	Password for password-protected groups	null
isBannedFromGroup	boolean	Whether the logged-in user is banned from the group	false

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_GUID_NOT_FOUND"
message	string	Human-readable error message	"The specified group does not exist."
details	string	Additional technical details	"Please provide a valid GUID for the group."

Get online group member count

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

Dart

List<String> guids =  [];
guids.add("cometchat-guid-1");
guids.add("cometchat-guid-11");

CometChat.getOnlineGroupMemberCount(guids,
        onSuccess: (Map<String, int> count) {
      debugPrint("Fetched Online Group Member Count Successfully : $count ");
    }, onError: (CometChatException e) {
      debugPrint("Online Group Member failed with exception: ${e.message}");
    });

This method returns a Map with the GUID of the group as the key and the online member count for that group as the value.

Response

On Success — A Map<String, int> containing the GUID of each group as the key and the online member count as the value:

Map Object:

Parameter	Type	Description	Sample Value
cometchat-guid-1	number	Online member count for the group	3
cometchat-guid-11	number	Online member count for the group	7

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_CHAT_API_FAILURE"
message	string	Human-readable error message	"Failed to fetch the requested data."
details	string	Additional technical details	"An unexpected error occurred while processing the request."

---

Next Steps

Create Group

Create new public, private, or password-protected groups

Retrieve Members

Get the list of members in a group