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

# Change Member Scope

> Guide to changing group member roles using the CometChat iOS SDK changeGroupMemberScope method.

<Info>
  **Quick Reference for AI Agents & Developers**

  * **Change scope:** `CometChat.updateGroupMemberScope(UID:GUID:scope:onSuccess:onError:)`
  * **Scopes:** `.admin`, `.moderator`, `.participant`
  * **Permission:** Only admin can change member scopes
  * **Related:** [Add Members](/sdk/ios/group-add-members) · [Kick Member](/sdk/ios/group-kick-member) · [Transfer Ownership](/sdk/ios/transfer-group-ownership)
</Info>

## Change Scope of a Group Member

In order to change the scope of a group member, you can use the `updateGroupMemberScope()` method.

### Method Parameters

| Parameter | Type                             | Description                                           |
| --------- | -------------------------------- | ----------------------------------------------------- |
| UID       | String                           | The UID of the member whose scope needs to be changed |
| GUID      | String                           | The GUID of the group                                 |
| scope     | [MemberScope](#memberscope-enum) | New scope: `.admin`, `.moderator`, `.participant`     |

### MemberScope Enum

| Scope        | Description         | Permissions                                |
| ------------ | ------------------- | ------------------------------------------ |
| .participant | Default scope       | Send/receive messages                      |
| .moderator   | Elevated privileges | Kick/ban members, delete messages          |
| .admin       | Full privileges     | All moderator + change scopes, add members |

<Warning>Only the **admin** of the group can change the scope of any member. The default scope of any member is `.participant`.</Warning>

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let guid = "cometchat-guid-1"
    let uid = "cometchat-uid-2"
    let scope: CometChat.MemberScope = .admin

    CometChat.updateGroupMemberScope(UID: uid, GUID: guid, scope: scope, onSuccess: { (response) in
        print("Scope changed: \(response)")
    }, onError: { (error) in
        print("Error: \(error?.errorDescription)")
    })
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payload - Change Scope to Admin">
  **Request Parameters:**

  | Parameter | Type                             | Description                                                   |
  | --------- | -------------------------------- | ------------------------------------------------------------- |
  | UID       | String                           | Unique identifier of the member. Example: `"cometchat-uid-2"` |
  | GUID      | String                           | Unique identifier of the group. Example: `"cometchat-guid-1"` |
  | scope     | [MemberScope](#memberscope-enum) | New scope for the member. Example: `.admin`                   |

  **Success Response:**

  | Parameter | Type   | Description                                                            |
  | --------- | ------ | ---------------------------------------------------------------------- |
  | response  | String | Success message. Example: `"Group member scope changed successfully."` |

  **After Scope Change to Admin:**

  | Effect      | Description                                             |
  | ----------- | ------------------------------------------------------- |
  | Permissions | Member now has full admin privileges                    |
  | Actions     | Can change other members' scopes, add/remove members    |
  | Event       | Other members receive `onGroupMemberScopeChanged` event |

  **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 - Change Scope to Moderator">
  **Request Parameters:**

  | Parameter | Type                             | Description                                                   |
  | --------- | -------------------------------- | ------------------------------------------------------------- |
  | UID       | String                           | Unique identifier of the member. Example: `"cometchat-uid-2"` |
  | GUID      | String                           | Unique identifier of the group. Example: `"cometchat-guid-1"` |
  | scope     | [MemberScope](#memberscope-enum) | New scope for the member. Example: `.moderator`               |

  **Success Response:**

  | Parameter | Type   | Description                                                            |
  | --------- | ------ | ---------------------------------------------------------------------- |
  | response  | String | Success message. Example: `"Group member scope changed successfully."` |

  **After Scope Change to Moderator:**

  | Effect      | Description                                             |
  | ----------- | ------------------------------------------------------- |
  | Permissions | Member now has moderator privileges                     |
  | Actions     | Can kick/ban members, delete messages                   |
  | Event       | Other members receive `onGroupMemberScopeChanged` event |
</Accordion>

<Accordion title="Sample Payload - Change Scope to Participant">
  **Request Parameters:**

  | Parameter | Type                             | Description                                                   |
  | --------- | -------------------------------- | ------------------------------------------------------------- |
  | UID       | String                           | Unique identifier of the member. Example: `"cometchat-uid-2"` |
  | GUID      | String                           | Unique identifier of the group. Example: `"cometchat-guid-1"` |
  | scope     | [MemberScope](#memberscope-enum) | New scope for the member. Example: `.participant`             |

  **Success Response:**

  | Parameter | Type   | Description                                                            |
  | --------- | ------ | ---------------------------------------------------------------------- |
  | response  | String | Success message. Example: `"Group member scope changed successfully."` |

  **After Scope Change to Participant:**

  | Effect      | Description                                             |
  | ----------- | ------------------------------------------------------- |
  | Permissions | Member now has basic participant privileges             |
  | Actions     | Can only send/receive messages                          |
  | Event       | Other members receive `onGroupMemberScopeChanged` event |
</Accordion>

***

## Real-Time Scope Change Events

*In other words, as a member of a group, how do I know when someone's scope is changed when my app is running?*

In order to receive real-time events whenever a group member's scope changes, you will need to implement the `onGroupMemberScopeChanged()` method of the `CometChatGroupDelegate`.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    class ViewController: UIViewController, CometChatGroupDelegate {
        
        override func viewDidLoad() {
            super.viewDidLoad()
            CometChat.groupdelegate = self
        }
        
        func onGroupMemberScopeChanged(action: ActionMessage, scopeChangeduser: User, scopeChangedBy: User, scopeChangedTo: String, scopeChangedFrom: String, group: Group) {
            print("\(scopeChangeduser.name ?? "") scope changed")
            print("From: \(scopeChangedFrom) To: \(scopeChangedTo)")
            print("Changed by: \(scopeChangedBy.name ?? "")")
            print("In group: \(group.name ?? "")")
        }
    }
    ```
  </Tab>

  <Tab title="Objective C">
    ```objc theme={null}
    @interface ViewController ()<CometChatGroupDelegate>
    @end

    @implementation ViewController

    - (void)viewDidLoad {
        [super viewDidLoad];
        [CometChat setGroupdelegate:self];
    }

    - (void)onGroupMemberScopeChangedWithAction:(Action *)action user:(User *)user scopeChangedTo:(NSString *)scopeChangedTo scopeChangedFrom:(NSString *)scopeChangedFrom group:(Group *)group {
        // User scope changed
    }

    @end
    ```
  </Tab>
</Tabs>

### onGroupMemberScopeChanged Parameters

| Parameter        | Type                                               | Description                  |
| ---------------- | -------------------------------------------------- | ---------------------------- |
| action           | ActionMessage                                      | Action message with details  |
| scopeChangeduser | [User](/sdk/ios/users-overview#user-properties)    | User whose scope was changed |
| scopeChangedBy   | [User](/sdk/ios/users-overview#user-properties)    | User who changed the scope   |
| scopeChangedTo   | String                                             | New scope value              |
| scopeChangedFrom | String                                             | Previous scope value         |
| group            | [Group](/sdk/ios/retrieve-groups#group-properties) | Group where change occurred  |

<Accordion title="Sample Payload - onGroupMemberScopeChanged Event">
  **Event Trigger:** Received via `CometChatGroupDelegate.onGroupMemberScopeChanged(action:scopeChangeduser:scopeChangedBy:scopeChangedTo:scopeChangedFrom:group:)`

  **ActionMessage Object:**

  | Parameter | Type                                               | Description                                                                      |
  | --------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
  | action    | String                                             | Action type. Example: `"scopeChanged"`                                           |
  | actionOn  | [User](/sdk/ios/users-overview#user-properties)    | User whose scope changed. Example: `{"uid": "user123", "name": "John Doe"}`      |
  | actionBy  | [User](/sdk/ios/users-overview#user-properties)    | User who changed the scope. Example: `{"uid": "admin1", "name": "Admin User"}`   |
  | actionFor | [Group](/sdk/ios/retrieve-groups#group-properties) | Group where change occurred. Example: `{"guid": "group123", "name": "My Group"}` |
  | oldScope  | String                                             | Original scope. Example: `"participant"`                                         |
  | newScope  | String                                             | Updated scope. Example: `"moderator"`                                            |

  **scopeChangeduser ([User](/sdk/ios/users-overview#user-properties) Object):**

  | Parameter | Type    | Description                                                           |
  | --------- | ------- | --------------------------------------------------------------------- |
  | uid       | String? | Unique identifier of the user. Example: `"user123"`                   |
  | name      | String? | Display name of the user. Example: `"John Doe"`                       |
  | avatar    | String? | URL to the user's avatar. Example: `"https://example.com/avatar.png"` |

  **scopeChangedBy ([User](/sdk/ios/users-overview#user-properties) Object):**

  | Parameter | Type    | Description                                         |
  | --------- | ------- | --------------------------------------------------- |
  | uid       | String? | Unique identifier of the admin. Example: `"admin1"` |
  | name      | String? | Display name of the admin. Example: `"Admin User"`  |

  **Scope Change Details:**

  | Parameter        | Type   | Description                                    |
  | ---------------- | ------ | ---------------------------------------------- |
  | scopeChangedTo   | String | New scope value. Example: `"moderator"`        |
  | scopeChangedFrom | String | Previous scope value. Example: `"participant"` |

  **group ([Group](/sdk/ios/retrieve-groups#group-properties) Object):**

  | Parameter | Type    | Description                                    |
  | --------- | ------- | ---------------------------------------------- |
  | guid      | String  | Unique group identifier. Example: `"group123"` |
  | name      | String? | Group display name. Example: `"My Group"`      |
</Accordion>

## Missed Group Member Scope Changed Events

*In other words, as a member of a group, how do I know when someone's scope is changed when my app is not running?*

When you retrieve the list of previous messages if a member's scope has been changed for any group that the logged-in user is a member of, the list of messages will contain an `Action` message.

### Action Message Properties (for missed events)

| Property  | Type                                               | Description                 |
| --------- | -------------------------------------------------- | --------------------------- |
| action    | String                                             | `"scopeChanged"`            |
| actionOn  | [User](/sdk/ios/users-overview#user-properties)    | User whose scope changed    |
| actionBy  | [User](/sdk/ios/users-overview#user-properties)    | User who changed the scope  |
| actionFor | [Group](/sdk/ios/retrieve-groups#group-properties) | Group where change occurred |
| oldScope  | String                                             | Original scope              |
| newScope  | String                                             | Updated scope               |

***

## Common Error Codes

| Error Code                        | Description                              | Resolution                                    |
| --------------------------------- | ---------------------------------------- | --------------------------------------------- |
| ERR\_GROUP\_NOT\_FOUND            | Group with specified GUID does not exist | Verify the GUID is correct                    |
| ERR\_UID\_NOT\_FOUND              | User with specified UID does not exist   | Verify the user UID                           |
| ERR\_GROUP\_NOT\_JOINED           | User is not a member of the group        | Join the group first                          |
| ERR\_NOT\_A\_MEMBER               | Target user is not a member of the group | User must be a member                         |
| ERR\_PERMISSION\_DENIED           | Logged-in user is not admin              | Only admin can change scopes                  |
| ERR\_CANNOT\_CHANGE\_OWNER\_SCOPE | Cannot change the group owner's scope    | Owner scope cannot be changed                 |
| ERR\_INVALID\_SCOPE               | Invalid scope value provided             | Use `.admin`, `.moderator`, or `.participant` |