Change Role

To invoke the API you will need 2 things. An instance of HMSPeer of the peer who's role you want to change and the HMSRole instance for the target role. All the peers that are in the current room are accessible via peers property of HMSRoom instance that you can get via room property of HMSSDK instance after successful room join. A list of all available roles in the current room can be accessed via roles property of HMSSDK

Once you have both you can invoke

 hmsSDK.changeRole(for: targetPeer, role: targetRole)

If the change role succeeds you will get a

func on(peer: HMSPeer, update: HMSPeerUpdate)

delegate callback with the the same peer you passed as targetPeer and a roleUpdated update type.

changeRole has an optional force parameter which is false by default meaning that changeRole is basically a polite request: "Would you like to change you role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a

func on(roleChangeRequest: HMSRoleChangeRequest)

delegate callback. At which point app can choose to show a prompt to the user asking for permission. If the user accepts, app should call

hmsSDK.accept(changeRole: roleChangeRequest)

which completes the changeRole loop. Both parties will receive a roleUpdated callback so that they both can do necessary UI updates. Now the user actually becomes a speaker and the audio publishing will start automatically.

Now lets imagine the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the force parameter comes in. When it is set to true the other party will not receive a confirmation roleChangeRequest but instead will straight away receive a new set of updated permissions and stop publishing. roleUpdated callback will still be fired so that the app can update the user's UI state.

Bulk Role Change

Bulk role change is used when you want to change roles of all users from a list of roles, to another role.

For example if peers join a room with a waiting role and you want to change them all to viewers then you'd use this API.

Here is the method signature.

func changeRolesOfAllPeers(to role: HMSRole, limitToRoles: [HMSRole]? = nil, completion: ((Bool, Error?) -> Void)? = nil)

1. role is the HMSRole they should be changed to.
2. limitToRoles is a list of HMSRole whose role should be changed.
3. completion is the optional completion handler to be invoked when the request succeeds or fails with an error.

You should avoid omitting limitToRoles param as this can result in accidentally changing roles you may not have intended such as the bots that provide recording and streaming with the roles beam.

Also bulk role changes are always forced, no dialog will be given for the peer to accept it, they will just be changed immediately.

Here's how the method could be called to change all guest and waiting roles to host:

func changeRoles(hmsSdk: HMSSDK) {
        var sourceRoles = roles.filter({ role in
            role.name == "guest" || role.name == "waiting"
        })
        var toRole = roles.first { $0.name == "host" }

        hmsSdk.changeRolesOfAllPeers(to: toRole, limitToRoles: sourceRoles)
    }

Bulk Role Change Errors

You may get the following errors for bulk role change:

You call changeRole(of: to: shouldAskForApproval:) method on HMSRoomModel instance.

try await roomModel.changeRole(of: /* instance of HMSPeerModel */, to: /* role's name as string */, shouldAskForApproval: /* optional boolean to denote if role should change immediately or after the participant's approval */)

How to approve the role change request

When someone changes role of a peer setting shouldAskForApproval flag to true, the peer receives a roleChangeRequests that they need to approve before their role changes. When you receive such request, it's appended in roleChangeRequests array that is a property on the HMSRoomModel instance. You handle the request by either approving on denying the request.

// accept current roleChangeRequest request
if let _ = roomModel.roleChangeRequests.last {
    try await roomModel.acceptChangeRoleRequest()
}

// decline current roleChangeRequest request
if let _ = roomModel.roleChangeRequests.last {
    try await roomModel.declineChangeRoleRequest()
}