> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-ios-ui-kit-sdk-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Group Members

> Guide to fetching group member lists using the CometChat iOS SDK GroupMembersRequest builder with pagination.

<Info>
  **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](/sdk/ios/group-add-members) · [Kick Member](/sdk/ios/group-kick-member) · [Groups Overview](/sdk/ios/groups-overview)
</Info>

## 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                  |

<Accordion title="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()` |
</Accordion>

### GroupMembersRequest Methods (After build())

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

***

## Retrieve Group 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.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: "cometchat-guid-1")
        .set(limit: 30)
        .build()
    ```
  </Tab>
</Tabs>

### Set Search Keyword

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

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: "cometchat-guid-1")
        .set(limit: 30)
        .set(searchKeyword: "abc")
        .build()
    ```
  </Tab>
</Tabs>

### Set Scopes

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

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let groupMembersRequest = GroupMembersRequest.GroupMembersRequestBuilder(guid: "cometchat-guid-1")
        .set(limit: 30)
        .set(scopes: ["admin", "participant"])
        .build()
    ```
  </Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    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)")
    })
    ```
  </Tab>

  <Tab title="Objective C">
    ```objc theme={null}
    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]);
    }];
    ```
  </Tab>
</Tabs>

<Accordion title="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](#groupmember-object-properties) 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](#memberscope-enum)                      | Member's scope in the group. Example: `.admin`                                                                     |
  | joinedAt     | Double                                                | Unix timestamp when member joined. Example: `1771586968.0`                                                         |
  | status       | [UserStatus](/sdk/ios/retrieve-users#userstatus-enum) | 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](#common-error-codes)):**

  | 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."` |
</Accordion>

<Accordion title="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](#groupmember-object-properties) 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](#memberscope-enum)                      | Member's scope (filtered to admin). Example: `.admin`                                                              |
  | joinedAt  | Double                                                | Unix timestamp when member joined. Example: `1771586968.0`                                                         |
  | status    | [UserStatus](/sdk/ios/retrieve-users#userstatus-enum) | Current online status. Example: `.online`                                                                          |

  **Error Response ([CometChatException](#common-error-codes)):**

  | 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"` |
</Accordion>

<Accordion title="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](#groupmember-object-properties) 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](#memberscope-enum)                      | Member's scope (filtered to moderator). Example: `.moderator`                 |
  | joinedAt  | Double                                                | Unix timestamp when member joined. Example: `1771587000.0`                    |
  | status    | [UserStatus](/sdk/ios/retrieve-users#userstatus-enum) | Current online status. Example: `.offline`                                    |
</Accordion>

***

## 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](/sdk/ios/retrieve-users#userstatus-enum) | `.online` or `.offline`                   |
| statusMessage | String?                                               | Custom status message                     |
| lastActiveAt  | Double                                                | Last active Unix timestamp                |
| scope         | [MemberScope](#memberscope-enum)                      | `.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 |