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

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

频道身份组定义

SDK 内定义频道身份组的结构为QChatChannelRole接口类。该接口类的内置方法如下：

单击展开查看 QChatChannelRole 的内置方法

方法	返回数据类型	说明
getRoleId	long	返回身份组 ID
getServerId	long	返回身份组所属服务器的 ID
getChannelId	long	返回身份组所属的频道的 ID
getParentRoleId	long	返回频道身份组所继承的服务器身份组的 ID
getName	String	返回身份组名称
getIcon	String	返回身份组图标的 URL
getExt	String	返回身份组的扩展字段
getResourceAuths	Map<QChatRoleResource, QChatRoleOption>	返回身份组的权限列表，其中: QChatRoleResource的说明请参见身份组权限类型 QChatRoleOption定义了权限的配置状态（即权限开启或关闭），包括： ALLOW：开启，表示身份组成员将拥有该权限 DENY：关闭，表示身份组成员无该权限 INHERIT：继承（针对频道自定义身份组来说，指继承自频道的 @everyone 身份组中对应的相同权限项的配置状态）
getType	QChatRoleType	返回身份组的类型，1 表示@everyone 身份组，2 表示自定义身份组
getCreateTime	long	返回身份组的创建时间
getUpdateTime	long	返回身份组配置的更新时间

前提条件

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

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

• 已创建服务器和频道。

实现方法

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

创建频道自定义身份组

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

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

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

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

• API 原型

  InvocationFuture<QChatAddChannelRoleResult> addChannelRole(QChatAddChannelRoleParam param);
  

• 示例代码

  QChatServerRole serverRole = getServerRole();
  NIMClient.getService(QChatRoleService.class).addChannelRole(new QChatAddChannelRoleParam(serverRole.getServerId(),serverRole.getRoleId(),885305L)).setCallback(
          new RequestCallback<QChatAddChannelRoleResult>() {
              @Override
              public void onSuccess(QChatAddChannelRoleResult result) {
                  //操作成功,返回Channe身份组信息
                  QChatChannelRole channelRole = result.getRole();
  
  
              }
  
              @Override
              public void onFailed(int code) {
                  //操作失败，返回错误code
              }
  
              @Override
              public void onException(Throwable exception) {
                  //操作异常
              }
          });
  
  

修改频道自定义身份组

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

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

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

• API 原型

  InvocationFuture<QChatUpdateChannelRoleResult> updateChannelRole(QChatUpdateChannelRoleParam param);
  

• 示例代码

  QChatChannelRole channelRole = getChannelRole();
  Map<QChatRoleResource, QChatRoleOption> resourceAuths = new HashMap<>();
  resourceAuths.put(QChatRoleResource.DELETE_MSG,QChatRoleOption.ALLOW);
  NIMClient.getService(QChatRoleService.class).updateChannelRole(new QChatUpdateChannelRoleParam(channelRole.getServerId(),channelRole.getChannelId(),channelRole.getRoleId(),resourceAuths)).setCallback(
          new RequestCallback<QChatUpdateChannelRoleResult>() {
              @Override
              public void onSuccess(QChatUpdateChannelRoleResult result) {
                  //操作成功,返回修改后的Channel身份组信息
                  QChatChannelRole channelRole = result.getRole();
              }
  
              @Override
              public void onFailed(int code) {
                  //操作失败，返回错误code
              }
  
              @Override
              public void onException(Throwable exception) {
                  //操作异常
              }
          });
  

删除频道身份组

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

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

• API 原型

  InvocationFuture<Void> removeChannelRole(QChatRemoveChannelRoleParam param);
  

其中 QChatRemoveChannelRoleParam 需要传入ServerId、ChannelId和身份组Id。

• 示例代码

  QChatChannelRole channelRole = getChannelRole();
  NIMClient.getService(QChatRoleService.class).removeChannelRole(new QChatRemoveChannelRoleParam(channelRole.getServerId(),channelRole.getChannelId(),channelRole.getRoleId())).setCallback(
          new RequestCallback<Void>() {
              @Override
              public void onSuccess(Void param) {
                  //操作成功
              }
  
              @Override
              public void onFailed(int code) {
                  //操作失败，返回错误code
              }
  
              @Override
              public void onException(Throwable exception) {
                  //操作异常
              }
          });
  

查询频道身份组

SDK 提供多个查询频道身份组的方法，具体请参见频道身份组相关查询。

相关参考

相关系统通知

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

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

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