群组管理

本文档旨在指导开发者如何使用融云即时通讯 Web IMLib SDK 实现创建群组、群组资料设置、踢出群组、退出群组、解散群组、转让群组等功能。

提示

• 此功能从 5.12.0 版本开始支持。
• 针对已经通过原群组功能接口/group/create.json 创建的群组，默认不支持调用群托管的相关功能接口，需要调用群组托管导入接口，设置群组所有者（群主）及群组的默认权限后才能使用。

开通服务

使用此功能前，您须在控制台开通信息托管服务。

群组操作

群组操作事件通知

群组操作包含：创建群组、群组资料设置、踢出群组、退出群组、解散群组、群组转让。可以通过 IGroupOperationInfo 中的 operation 来区分操作类型。

提示

• 事件监听器应全局注册，且仅注册一次，避免重复接收事件通知。
• 事件回调数据类型为 IGroupOperationInfo。

示例代码

javascript

RongIMLib.addEventListener(Events.GROUP_OPERATION, (data) => {
  // data 为 IGroupOperationInfo 类型，通过 operation 来判断操作类型
  console.log('群组操作变更', data);
});

群组资料变更通知

调用 updateGroupInfo 方法，成功更新群资料后，群内所有成员将收到 Events.GROUP_INFO_CHANGED 事件。

提示

• 事件监听器应全局注册，且仅注册一次，避免重复接收事件通知。
• 事件回调数据类型为 IGroupInfoChanged。
• 通知数据仅包含发生变更的字段，未修改的字段不会包含在事件数据中

示例代码

javascript

RongIMLib.addEventListener(Events.GROUP_INFO_CHANGED, (data) => {
  console.log('群组资料变更通知', data);
});

创建群组

调用 createGroup 方法可创建新群组。

接口

JavaScript

RongIMLib.createGroup(groupInfo, inviteeUserIds)

参数说明

参数	类型	必填	说明
groupInfo	IGroupInfoOption	是	群组信息。
inviteeUserIds	string[]	否	可选邀请成员列表，最多 30 人。为空表示不邀请成员

• groupInfo 参数说明：

属性名	类型	必填	描述
groupId	string	是	群组 ID：最大长度 64 个字符。支持大小写英文字母与数字的组合。
groupName	string	是	群组名称：最大长度 64 个字符。不可设置为纯空格。
portraitUri	string	否	群头像 URL 地址：长度不超过 128 个字符。
introduction	string	否	群简介：最大长度不超过 512 个字符。
notice	string	否	群公告：最大长度不超过 1024 个字符。
extProfile	{[key: string]: string}	否	扩展信息：在现在群信息基础上，开发者可根据自身业务需求添加自定义扩展属性（Key、Value），最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用，否则返回设置失败。
joinPermission	GroupJoinPermission	否	主动加入群权限：不用验证、群主验证（默认）、群管理员及群主验证、不允许任何人加入，不设置按默认值处理。
removeMemberPermission	GroupOperationPermission	否	将群成员移出群组权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。
invitePermission	GroupOperationPermission	否	谁可以邀请他人入群：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。
inviteHandlePermission	GroupInviteHandlePermission	否	邀请加入群组处理方式：不需要被邀请人同意（默认）、需要被邀请人同意，不设置按默认值处理。
groupInfoEditPermission	GroupOperationPermission	否	修改群资料及权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。。该属性仅支持群主修改
memberInfoEditPermission	GroupMemberInfoEditPermission	否	设置群成员资料：仅自已、群主+自已、群主+群管理员+自已（默认），不设置按默认值处理。

示例代码

javascript

const groupInfo = {
  // 必填，最大长度 64 个字符。支持大小写英文字母与数字的组合
  groupId: 'group001',
  // 必填，最大长度 64 个字符
  groupName: 'groupName',
  // 自定义属性需要通过开发者后台或 API 设置后才能使用，否则返回设置失败
  extProfile: {},
};

const memberIdsArr = ['userId001', 'userId002'];
const res = await RongIMLib.createGroup(groupInfo, memberIdsArr);
console.info('创建群组结果', res);

提示

1. 创建群组成功，群主收到 Events.GROUP_OPERATION 监听，事件返回数据中 operation 操作类型值为 0，对应枚举 GroupOperation.CREATE。

2. 当设置了inviteeUserIds 时，如果 inviteHandlePermission 为 GroupInviteHandlePermission.FREE，被邀请人会自动加入群组。群组内所有成员会收到 Events.GROUP_OPERATION 监听，事件返回数据中 operation 操作类型值为 1，对应枚举 GroupOperation.JOIN。

3. 当设置了inviteeUserIds 时，如果 inviteHandlePermission 为 GroupInviteHandlePermission.INVITEE_VERIFY

   • 当前用户接口会返回 processCode 值为 25427，表示需要等待邀请人同意后才能加入群组。
   • 被邀请人会收到 Events.GROUP_APPLICATION_EVENT 事件，需要调用 acceptGroupInvite 同意后才能加入群组。

修改群组资料

调用 updateGroupInfo 可修改群名称、公告、权限等资料。

提示

• 仅 groupId 为必填项，其他字段可选。接口仅更新传入的字段，未传入字段保持不变
• 成功更新后，群成员收到 Events.GROUP_INFO_CHANGED 事件，仅包含变更字段。

接口

JavaScript

RongIMLib.updateGroupInfo(groupInfo)

参数说明

参数	类型	必填	说明
groupInfo	IGroupInfoOption	是	群组信息。

示例代码

javascript

const groupInfo = {
  // 必填，最大长度 64 个字符。支持大小写英文字母与数字的组合
  groupId: 'group001',
  introduction: 'group introduction',
};

const res = await RongIMLib.updateGroupInfo(groupInfo);
console.info('修改群组资料结果', res);

踢出群组

调用 kickGroupMembers 将成员移出群组，单次最多移除 100 人。

提示

• 成功后，群内成员收到 Events.GROUP_OPERATION 事件，operation=2（GroupOperation.KICK）。
• 群主不可被踢。
• 操作受 removeMemberPermission 权限限制，仅符合权限者可操作。

接口

JavaScript

RongIMLib.kickGroupMembers(groupId, userIds, config)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
userIds	string[]	是	要退出的群成员 ID 列表。
config	IQuitGroupConfig	否	配置选项，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config 默认为都移除。

示例代码

javascript

const groupId = 'group001';
const memberIds = ['user01', 'user02'];
const config = {
    // 默认为都移除
    removeMuteStatus: true, 
    // 默认为都移除
    removeWhiteList: true,
    // 默认为都移除
    removeFollow: true,
  }
const res = await RongIMLib.kickGroupMembers(groupId, memberIds, config)
console.info('踢出群组结果', res);

退出群组

调用 quitGroup 主动退出群组。

提示

退出成功，群内成员收到 Events.GROUP_OPERATION 事件，operation=3（GroupOperation.QUIT）

接口

JavaScript

RongIMLib.quitGroup(groupId, config)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
config	IQuitGroupConfig	否	配置选项，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。

示例代码

javascript

const groupId = 'group001';
const res = await RongIMLib.quitGroup(groupId)
console.info('退出群组结果', res);

提示

1. 群主调用 quitGroup 方法返回 25417 状态码提示：群主不能被踢出/退出群组。
2. 群主需要先调用 transferGroupOwner 接口转让群组后再退出群组。

解散群组

调用 dismissGroup 解散群组，解散后群会话消息保留，历史消息不删除。

提示

• 只有群主有权解散群组。
• 成功后，群成员收到 Events.GROUP_OPERATION 事件，operation=4（GroupOperation.DISMISS）

接口

JavaScript

RongIMLib.dismissGroup(groupId)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。

示例代码

javascript

const groupId = 'group001';
const res = await RongIMLib.dismissGroup(groupId)
console.info('解散群组结果', res);

转让群组

调用 transferGroupOwner 将群组转让给其他用户。

提示

• 仅群主可转让。
• 成功后，群内成员收到 Events.GROUP_OPERATION 事件，operation=7（GroupOperation.TRANSFER_GROUP_OWNER）。
• 若在转让时选择了退出群组，还会收到 operation=3（GroupOperation.QUIT）的退出事件。

接口

JavaScript

RongIMLib.transferGroupOwner(groupId, newOwnerId, quitGroup, config);

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
newOwnerId	string	是	转让后的群主用户 ID。
quitGroup	boolean	否	转让后是否自动退出群，默认 false
config	IQuitGroupConfig	否	仅在 quitGroup 为 true 时生效，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。

示例代码

javascript

// 必填，群组 ID
const groupId = 'group001';
// 必填，转让后的群主用户ID
const newOwnerId = 'newOwnerId';
// 转让后是否退出群组，默认 false。
const quitGroup = true; 
// 该配置参数仅在 quitGroup 为 true 时生效
const config = {
    // 默认为都移除
    removeMuteStatus: true, 
    // 默认为都移除
    removeWhiteList: true,
    // 默认为都移除
    removeFollow: true,
}
const res = await RongIMLib.transferGroupOwner(groupId, newOwnerId, quitGroup, config);
console.info('转让群组结果', res);

群组备注名

群组备注名仅对当前用户生效。当群组中有新消息产生且该用户处于离线状态时，推送通知标题将优先显示设置的群备注名。如果未设置，则默认显示群名称。

群名称备注名更新多端同步通知

当群备注名被设置或移除成功后，其他已登录终端会收到 Events.GROUP_REMARK_CHANGED_SYNC 事件通知，实现多端同步。

提示

• 事件监听器应全局注册，且仅注册一次，避免重复接收事件通知。
• 事件回调数据类型为 IGroupRemarkChangedSync。

示例代码

javascript

RongIMLib.addEventListener(Events.GROUP_REMARK_CHANGED_SYNC, (data) => {
  console.log('群名称备注名更新多端同步通知', data);
});

设置群组备注名

调用 setGroupRemark 方法为群组设置备注名。

接口

JavaScript

RongIMLib.setGroupRemark(groupId, remark)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
remark	string	是	群备注名。设置为 '' 代表移除。不允许为纯空格。字符串长度不超过 64 个字符，如群备注名已存在则做替换处理，以最后一次设置为准。

示例代码

javascript

const groupId = 'group001';
// 设置为 '' 代表移除。字符串长度不超过 64 个字符，如群备注名已存在则做替换处理，以最后一次设置为准
const remark = 'remark';
const res = await RongIMLib.setGroupRemark(groupId, remark);
// 需要输入存在的群组 ID，否则无法查询到群组信息，打印语句会抛异常
console.info('设置群组备注名结果', res);

查询群组备注名

可通过 getGroupsInfo 方法查询群组资料，返回数据中包含群备注名信息。

接口

JavaScript

RongIMLib.getGroupsInfo(groupIds)

参数说明

参数	类型	必填	说明
groupIds	string[]	是	群 ID 数组，单次最多支持 20 个群组

注意

若输入不存在的群组 ID，将无法查询到相关信息，执行时控制台可能抛出异常。

示例代码

javascript

// 必填项，群 ID 数组，单次查询最多支持 20 个群组。
const groupIds = ['group001']
const res = await RongIMLib.getGroupsInfo(groupIds);
// 需要输入存在的群组 ID，否则无法查询到群组信息，打印语句会抛异常
console.info('群组备注名称', res[0].remark);