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

频道下 @everyone 身份组的属性（例如成员）默认继承自服务器的 @everyone 身份组，且权限继承自服务器身份组的权限之和。

频道身份组数据结构

频道身份组由QChatChannelRole定义，其参数说明如下：

参数	类型	说明
roleId	string	频道身份组 ID
serverId	string	频道身份组所属服务器的 ID
channelId	string	频道身份组所属的频道的 ID
parentRoleId	string	频道身份组所继承的服务器身份组的 ID
name	string	频道身份组名称
icon	string	频道身份组图标的 URL
ext	string	频道身份组的扩展字段
auths	QChatRoleAuth	频道身份组的权限
type	TRoleType	频道身份组的类型，everyone：@everyone 身份组，custom: 自定义身份组
createTime	number	频道身份组的创建时间
updateTime	number	频道身份组的更新时间

实现方法

以下两个时序图分别展示了服务器普通成员（用户B）和服务器创建者（用户A）进行频道身份组管理前需要实现的业务逻辑。

创建频道自定义身份组

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

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

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

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

• API 原型

  addChannelRole(options: AddChannelRoleOptions): Promise<QChatChannelRole>
  

• 示例代码

  let serverRole = await qchat.qchatRole.createServerRole({
  "serverId": "1377422",
  "name": "serverRole1",
  })
  
  const channelRole = await qchat.qchatRole.addChannelRole({
  "serverId": "1377422",
  "channelId": "1099153",
  "parentRoleId": serverRole.roleId
  })
  
  console.log(channelRole)
  // {
  //     "serverId": "1377422",
  //     "roleId": "1115969",
  //     "parentRoleId": "1246291",
  //     "channelId": "1099153",
  //     "name": "role1",
  //     "auths": {
  //         "manageChannel": "ignore",
  //         "manageRole": "ignore",
  //         "sendMsg": "ignore",
  //         "recallMsg": "ignore",
  //         "deleteMsg": "ignore",
  //         "remindOther": "ignore",
  //         "remindEveryone": "ignore",
  //         "manageBlackWhiteList": "ignore"
  //     },
  //     "type": "custom",
  //     "createTime": 1646191891861,
  //     "updateTime": 1646191891861
  // }
  
  

修改频道自定义身份组

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

• 调用该方法必须先拥有manageRole权限和manageChannel权限，且必须是该频道的成员。如果没有权限，调用该方法将返回 403 错误码。
• 用户无法配置自己没有的权限。例如用户没有权限A，则无法修改权限A 的配置。
• 用户无法将自己拥有的某个权限在全部所属身份组中都设置为deny。例如用户属于 10 个身份组且这 10 个身份组都开启了权限A，那么用户最多可以将其中 9 个身份组的权限A 设置为deny。
• 只有修改频道身份组中的权限状态，才会触发系统通知。具体的触发条件和接收条件请参考圈组系统通知。

• API 原型

  updateChannelRole(options: UpdateChannelRoleOptions): Promise<QChatChannelRole>
  

• 示例代码

await qchat.qchatRole.updateChannelRole({
  "serverId": "YOUR_SERVERID",
  "channelId": "YOUR_CHANNELID",
  "roleId": "YOUR_ROLEID",
  "auths": {
    "accountNameOther": "deny"
  }
})

删除频道身份组

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

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

• API 原型

  removeChannelRole(options: RemoveChannelRoleOptions): Promise<void>
  

• 示例代码

  await qchat.qchatRole.removeChannelRole({
  "serverId": "YOUR_SERVERID",
      "channelId": "YOUR_CHANNELID",
  "roleId": "YOUR_ROLEID"
  })
  
  

API 参考

API	说明
addChannelRole	创建频道身份组
updateChannelRole	修改频道身份组
removeChannelRole	删除频道身份组