Skip to main content
Key Benefit: Implement role-based access control to manage user permissions and moderation capabilities, ensuring proper channel governance and security.

​
Feature Overview

Role Management enables you to assign and manage different permission levels within chat channels. Roles define varying levels of access and permissions that can be assigned to users, allowing for structured channel governance and moderation.

Role Assignment

Add roles to members
  • Assign moderator permissions
  • Grant custom role access
  • Promote trusted users
  • Bulk role operations

Role Removal

Remove roles from members
  • Demote moderators
  • Revoke permissions
  • Manage role transitions
  • Maintain role hierarchy
Channel Type Limitation: Role management applies only to Live and Community channels. This feature is not available for Conversation and Broadcast channels.

​
Role Hierarchy

Understanding the role hierarchy is essential for effective channel governance:
RoleAuthority LevelCapabilities
Channel CreatorHighestAutomatically assigned as moderator, cannot be removed
ModeratorsHighCan promote/demote other users, manage channel activities
Custom RolesVariableApplication-defined permissions
MembersStandardBasic channel participation
Important Rules:
  • The channel creator is automatically assigned as the channel moderator
  • The last moderator cannot leave a community (error will be displayed)
  • Channel moderators can promote users to moderators
  • Channel moderators can demote other moderators to regular members

​
Implementation Guide

  • Add Roles
  • Remove Roles
Assign roles to channel membersGrant users specific roles within channels to provide them with appropriate permissions and responsibilities.

​
Core Operation

MethodPurposeWhen to Use
addRoleAssign role to usersPromoting users to moderators or custom roles

​
Code Examples

// Add a role to member
do {
let success = try await channelModeration.addRole("<role>", userIds: ["<user-id>"])
} catch {
// Handle error here
}
Best Practice: Always validate user membership before assigning roles. Consider implementing confirmation dialogs for role assignments, especially for moderator promotions.

​
Best Practices

Effective role management approaches
  • Assign roles based on user contribution and trustworthiness
  • Implement a clear role hierarchy that matches your community structure
  • Use gradual promotion paths (member → moderator) rather than immediate elevation
  • Regularly review role assignments to ensure they remain appropriate
  • Document role responsibilities clearly for users and moderators
Strategic role assignment creates well-functioning community governance.
Managing role permissions effectively
  • Define clear permission boundaries for each role level
  • Avoid overlapping permissions that could cause confusion
  • Implement the principle of least privilege (minimal necessary permissions)
  • Use custom roles for specific use cases rather than overloading standard roles
  • Test role permissions thoroughly before deployment
Well-defined permissions prevent conflicts and ensure security.
Monitoring and managing moderator actions
  • Track moderator actions for accountability and training
  • Implement escalation procedures for complex moderation decisions
  • Provide moderator guidelines and training materials
  • Regular moderator performance reviews and feedback
  • Establish procedures for moderator misconduct
Proper oversight ensures consistent and fair moderation.
Robust error management for role operations
  • Validate user membership before role assignment
  • Check for last moderator scenarios before role removal
  • Implement rollback mechanisms for failed operations
  • Provide clear error messages for different failure scenarios
  • Log role changes for audit trails and troubleshooting
Comprehensive error handling prevents governance disruptions.

Member Management

Channel Membership Add and remove channel members

Ban Management

User Restrictions Ban and unban problematic users

Mute Management

Message Restrictions Control user messaging permissions
Implementation Strategy: Start with basic role assignment and removal, then add validation and error handling. Implement role transitions and bulk operations for advanced use cases. Focus on creating clear governance policies alongside the technical implementation.