Change Member Scope

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

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 · Kick Member · Transfer Ownership

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

Only the admin of the group can change the scope of any member. The default scope of any member is .participant.

Swift

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)")
})

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	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):

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

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

---

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.

Swift

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 ?? "")")
    }
}

Objective C

@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

onGroupMemberScopeChanged Parameters

Parameter	Type	Description
action	ActionMessage	Action message with details
scopeChangeduser	User	User whose scope was changed
scopeChangedBy	User	User who changed the scope
scopeChangedTo	String	New scope value
scopeChangedFrom	String	Previous scope value
group	Group	Group where change occurred

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	User whose scope changed. Example: {"uid": "user123", "name": "John Doe"}
actionBy	User	User who changed the scope. Example: {"uid": "admin1", "name": "Admin User"}
actionFor	Group	Group where change occurred. Example: {"guid": "group123", "name": "My Group"}
oldScope	String	Original scope. Example: "participant"
newScope	String	Updated scope. Example: "moderator"

scopeChangeduser (User 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 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 Object):

Parameter	Type	Description
guid	String	Unique group identifier. Example: "group123"
name	String?	Group display name. Example: "My Group"

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	User whose scope changed
actionBy	User	User who changed the scope
actionFor	Group	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