频道身份组用于对用户在频道维度进行权限控制。频道身份组分为两种，@everyone 身份组和自定义身份组。其中 @everyone 身份组在频道创建时默认自动创建，自定义身份组需要用户手动创建。频道的@everyone 身份组和自定义身份组成员均默认为频道所有成员。

频道下 @everyone 身份组的属性和权限默认继承自服务器的 @everyone 身份组。

频道身份组定义

SDK 内定义频道身份组的类为NIMQChatChannelRole。该类的成员参数如下：

单击展开查看 NIMQChatChannelRole 的成员参数

方法	类型	说明
roleId	unsigned long long	身份组 ID
serverId	unsigned long long	身份组所属服务器的 ID
parentRoleId	unsigned long long	被继承服务器的身份组 ID
channelId	unsigned long long	频道 ID
name	NSString	身份组名称
icon	NSString	身份组图标的 URL
ext	NSString	身份组的扩展字段
auths	NSArray<NIMQChatPermissionStatusInfo*>	NIMQChatPermissionStatusInfo类表示身份组权限信息，包含type和status两个参数: type:权限类型，在NIMQChatPermissionType内定义，具体权限说明请参见身份组权限类型 status:NIMQChatPermissionStatus内定义了权限的配置状态，包括 NIMQChatPermissionStatusDeny:关闭，即表示身份组成员无该权限 NIMQChatPermissionStatusExtend：继承继承（针对频道自定义身份组来说，指继承自频道的 @everyone 身份组中对应的相同权限项的配置状态） NIMQChatPermissionStatusAllow：开启，即表示身份组成员拥有该权限
type	NIMQChatRoleType	返回身份组的类型，NIMQChatRoleTypeEveryOne 表示 @everyone 身份组，NIMQChatRoleTypeCustom 表示自定义身份组
createTime	NSTimeInterval	身份组的创建时间
updateTime	NSTimeInterval	身份组配置的更新时间

前提条件

• 已注册onRecvSystemNotification:监听圈组的系统通知。示例代码参见圈组系统通知收发。

  具体与频道身份组相关的系统通知类型，见本文末尾的相关系统通知。

• 已创建服务器并创建频道。

实现方法

以下两个时序图分别展示了服务器普通成员（用户B）和服务器创建者（用户A）进行频道身份组管理前需要实现的业务逻辑。普通成员需要拥有管理频道和管理角色的权限才能创建和管理频道身份组，而服务器创建者默认拥有全量权限，可以在频道内直接创建并管理频道身份组。

服务器普通成员管理频道身份组：

sequenceDiagram



note over QChat 实例: 初始化与登录

note over QChat 实例: 用户A 将相应权限授予用户 B
用户A ->> QChat 实例: 创建服务器
用户A ->> QChat 实例: 创建服务器身份组
用户A ->> QChat 实例: 修改服务器身份组
note over 用户A: 修改时将该身份组的<br>管理角色权限和管理频道权限开启，<br>使该身份组成员拥有这两项权限
用户A ->> QChat 实例: 邀请用户B 加入服务器
用户B ->> QChat 实例: 接受邀请加入服务器
note right of 用户B:  需先加入服务器<br>才能被加为身份组成员
用户A ->> QChat 实例: 将用户B 加入服务器身份组
note over 用户A: 用户B 加入该身份组后，<br>获得管理角色权限和管理频道权限

note over QChat 实例: 用户B 可访问用户A 创建的频道
用户A ->> QChat 实例: 在服务器内创建频道
note over 用户A: 用户B 在以下两种情况下可访问频道（即成为频道成员）：<br>1. 创建的是公开频道，且用户B 未被加入频道黑名单<br>2. 创建的私密频道，且用户B 被加入频道白名单

note over QChat 实例: 用户B 设置频道身份组
note over 用户B: 用户B 可访问频道，且拥有<br>管理角色权限和管理频道权限，<br>所以可创建和管理频道身份组
用户B ->> QChat 实例: 创建频道自定义身份组
用户B ->> QChat 实例: 修改频道自定义身份组
用户B ->> QChat 实例: 此处省略其他接口调用
用户B ->> QChat 实例: 删除频道自定义身份组

服务器创建者管理频道身份组：

sequenceDiagram



note over QChat 实例: 初始化与登录
note over QChat 实例: 创建服务器
note over QChat 实例: 创建服务器身份组
note over QChat 实例: 将其他用户加入服务器
note over QChat 实例: 将其他用户加入服务器身份组
note over QChat 实例: 创建频道
note over QChat 实例: 管理频道身份组
用户A ->> QChat 实例: 创建频道自定义身份组
用户A ->> QChat 实例: 修改频道自定义身份组
用户A ->> QChat 实例: 此处省略其他接口调用
用户A ->> QChat 实例: 删除频道自定义身份组

创建频道自定义身份组

默认情况下，频道直接使用服务器身份组来控制权限。如有需要，可调用addChannelRole:completion:方法新增一个频道身份组，新增的频道身份组的权限配置默认继承自服务器身份组（调用时必须通过serverRoleId指定新增的频道身份组继承自哪个服务器身份组）。

调用该方法必须先拥有管理角色权限（NIMQChatPermissionTypeManageRole）和频道管理权限（NIMQChatPermissionTypeManageChannel），且必须是该频道的成员。如果没有权限，调用该方法将返回 403 错误码。

新创建的频道身份组和被继承的服务器身份组有以下联系：

• 公开频道的身份组成员等于被继承的服务器身份组成员去掉频道黑名单成员和频道黑名单身份组成员；私密频道的身份组成员是同时存在于频道白名单和被继承的服务器身份组的公共成员，以及同时存在于频道白名单身份组和被继承的服务器身份组的公共成员。
• 刚创建时两者权限一样。频道身份组刚创建时所有权限配置都为INHERIT，因此实际权限和被继承的服务器身份组一样，之后可以调用updateChannelRole方法手动修改，使频道身份组和服务器身份组拥有不一样的权限。
• 频道身份组的parentRoleId等于被继承的服务器身份组的roleId。

• API 原型

  - (void)addChannelRole:(NIMQChatAddChannelRoleParam *)param
                  completion:(nullable NIMQChatAddChannelRoleHandler)completion;
  

• 示例代码

  id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
  NIMQChatAddChannelRoleParam *param = [[NIMQChatAddChannelRoleParam alloc] init];
  param.serverId = 123456;
  param.channelId = 121212;
  param.parentRoleId = 111;
  [qchatRoleManager addChannelRole:param
              completion:^(NSError *__nullable error, NIMQChatChannelRole *__nullable result) {
      // your code
  }];
  
  

修改频道自定义身份组

调用updateChannelRole:completion: 方法可修改频道自定义身份组的权限配置。

该方法的入参结构为NIMQChatUpdateChannelRoleParam，需要传入频道身份组所属的服务器 ID、频道 ID、频道身份组 ID 和待更新的权限数组。

• 调用该方法必须先拥有NIMQChatPermissionTypeManageRole权限和NIMQChatPermissionTypeManageChannel权限，且必须是该频道的成员。如果没有权限，调用该方法将返回 403 错误码。
• 用户无法配置自己没有的权限。例如用户没有权限A，则无法修改权限A 的配置。
• 用户无法将自己拥有的某个权限在全部所属身份组中都设置为关闭（NIMQChatPermissionStatusDeny）。例如用户有 10 个身份组且这 10 个身份组都开启权限A，那么用户最多可以将其中 9 个身份组的权限A 设置为NIMQChatPermissionStatusDeny。

• API 原型

  - (void)updateChannelRole:(NIMQChatUpdateChannelRoleParam *)param
                  completion:(nullable NIMQChatUpdateChannelRoleHandler)completion;
  

• 示例代码

  id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
  NIMQChatUpdateChannelRoleParam *param = [[NIMQChatUpdateChannelRoleParam alloc] init];
  param.serverId = 123456;
  param.channelId = 121212;
  param.roleId = 111;
  NIMQChatPermissionStatusInfo *info = [[NIMQChatPermissionStatusInfo alloc] init];
  info.type = NIMQChatPermissionTypeRemindOther;
  info.status = NIMQChatPermissionStatusExtend;
  param.commands = @[info];
  [qchatRoleManager updateChannelRole:param
              completion:^(NSError *__nullable error, NIMQChatChannelRole *__nullable result) {
      // your code
  }];
  

删除频道身份组

调用 removeChannelRole:completion:可删除频道身份组。

调用该方法必须先拥有NIMQChatPermissionTypeManageRole权限和NIMQChatPermissionTypeManageChannel权限，且必须是该频道的成员。如果没有权限，调用该方法将返回 403 错误码。

• API 原型

  - (void)removeChannelRole:(NIMQChatRemoveChannelRoleParam *)param
                  completion:(nullable NIMQChatRemoveChannelRoleHandler)completion;
  

其中NIMQChatRemoveChannelRoleParam需要传入服务器 ID、频道 ID 和身份组 ID。

• 示例代码

  id<NIMQChatRoleManager> qchatRoleManager = [[NIMSDK sharedSDK] qchatRoleManager];
  NIMQChatRemoveChannelRoleParam *param = [[NIMQChatRemoveChannelRoleParam alloc] init];
  param.serverId = 123456; //服务器ID
  param.channelId = 121212; //频道ID
  param.roleId = 111; //身份组ID
  [qchatRoleManager removeChannelRole:param
              completion:^(NSError *__nullable error) {
      // your code
  }];
  

相关参考

相关系统通知

圈组系统通知的类型在NIMQChatSystemNotificationType枚举中定义，与频道身份组相关的内置系统通知类型如下：

枚举值	说明
NIMQChatSystemNotificationTypeChannelRoleAuthUpdate	更新“频道身份组”权限

该系统通知的接收条件，请参见服务端文档的身份组权限相关事件通知。