跳到主要内容

版本:5.X

群组管理

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

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

开通服务

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

群组操作

群组操作事件通知

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

监听建议全局注册切仅注册一次,多次调用会通知多次。通知数据为 IGroupOperationInfo 类型。

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

群组资料变更通知

调用 updateGroupInfo 群组信息更新成功后,群组内的所有成员会收到 Events.GROUP_INFO_CHANGED 事件,事件通知仅包含变更项,未修改项值不会再 Events.GROUP_INFO_CHANGED 事件中返回。

监听建议全局注册切仅注册一次,多次调用会通知多次。通知数据为 IGroupInfoChanged 类型。

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

创建群组

您可以调用 createGroup 方法创建一个新群组。

参数名类型必填描述
groupInfoIGroupInfoOption群组信息。
inviteeUserIdsstring[]您可以选择在创建群的同时,邀请用户加入群组。可以为空,一次最多允许 30 个用户加入。

groupInfo 参数介绍:

属性名类型必填描述
groupIdstring群组 ID:最大长度 64 个字符。支持大小写英文字母与数字的组合。
groupNamestring群组名称:最大长度 64 个字符。不可设置为纯空格。
portraitUristring群头像 URL 地址:长度不超过 128 个字符。
introductionstring群简介:最大长度不超过 512 个字符。
noticestring群公告:最大长度不超过 1024 个字符。
extProfile{[key: string]: string}扩展信息:在现在群信息基础上,开发者可根据自身业务需求添加自定义扩展属性(Key、Value),最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用,否则返回设置失败。
joinPermissionGroupJoinPermission主动加入群权限:不用验证、群主验证(默认)、群管理员及群主验证、不允许任何人加入,不设置按默认值处理。
removeMemberPermissionGroupOperationPermission将群成员移出群组权限:群主(默认)、群主+群管理员、所有人,不设置按默认值处理。
invitePermissionGroupOperationPermission谁可以邀请他人入群:群主(默认)、群主+群管理员、所有人,不设置按默认值处理。
inviteHandlePermissionGroupInviteHandlePermission邀请加入群组处理方式:不需要被邀请人同意(默认)、需要被邀请人同意,不设置按默认值处理。
groupInfoEditPermissionGroupOperationPermission修改群资料及权限:群主(默认)、群主+群管理员、所有人,不设置按默认值处理。。该属性仅支持群主修改
memberInfoEditPermissionGroupMemberInfoEditPermission设置群成员资料:仅自已、群主+自已、群主+群管理员+自已(默认),不设置按默认值处理。
提示
  1. 创建群组成功,群主收到 Events.GROUP_OPERATION 监听,事件返回数据中 operation 操作类型值为 0,对应枚举 GroupOperation.CREATE

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

  3. 当设置了inviteeUserIds 时,如果 inviteHandlePermissionGroupInviteHandlePermission.INVITEE_VERIFY

    • 当前用户接口会返回 processCode 值为 25427,表示需要等待邀请人同意后才能加入群组。
    • 被邀请人会收到 Events.GROUP_APPLICATION_EVENT 事件,需要调用 acceptGroupInvite 同意后才能加入群组。
const groupInfo = {
// 必填,最大长度 64 个字符。支持大小写英文字母与数字的组合
groupId: 'group001',
// 必填,最大长度 64 个字符
groupName: 'groupName',
// 自定义属性需要通过开发者后台或 API 设置后才能使用,否则返回设置失败
extProfile: {},
};

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

修改群组资料

您可以调用 updateGroupInfo 方法修改群组名称、公告、权限等其他资料。

修改群组资料时,只有 groupId 为必填项,其他字段可按需设置,接口只会更新有修改的项。

群组信息更新成功后,群组内的所有成员会收到 Events.GROUP_INFO_CHANGED 事件,事件通知仅包含变更项,未修改项值不会再 Events.GROUP_INFO_CHANGED 事件中返回。

groupInfo 参数介绍:

属性名类型必填描述
groupIdstring群组 ID:最大长度 64 个字符。支持大小写英文字母与数字的组合。
groupNamestring群组名称:最大长度 64 个字符。不可设置为纯空格。
portraitUristring群头像 URL 地址:长度不超过 128 个字符。
introductionstring群简介:最大长度不超过 512 个字符。
noticestring群公告:最大长度不超过 1024 个字符。
extProfile{[key: string]: string}扩展信息:在现在群信息基础上,开发者可根据自身业务需求添加自定义扩展属性(Key、Value),默认最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用,否则返回设置失败。
joinPermissionGroupJoinPermission主动加入群权限:不用验证、群主验证、群管理员及群主验证、不允许任何人加入。
removeMemberPermissionGroupOperationPermission将群成员移出群组权限:群主、群主+群管理员、所有人。
invitePermissionGroupOperationPermission谁可以邀请他人入群:群主、群主+群管理员、所有人。
inviteHandlePermissionGroupInviteHandlePermission邀请加入群组处理方式:不需要被邀请人同意、需要被邀请人同意。
groupInfoEditPermissionGroupOperationPermission修改群资料及权限:群主、群主+群管理员、所有人。
memberInfoEditPermissionGroupMemberInfoEditPermission设置群成员资料:仅自已、群主+自已、群主+群管理员+自已。
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 权限限制,符合限制条件的角色才可以进行操作。
参数名类型必填描述
groupIdstring群组 ID。
memberIdsarray要踢出的成员 ID 列表。
configIQuitGroupConfig配置选项,控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config 默认为都移除。
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

参数名类型必填描述
groupIdstring群组 ID。
configIQuitGroupConfig配置选项,控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config,默认在退出群组时会全部移除。
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

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

转让群组

您可以调用 transferGroupOwner 方法将群组转让给其他用户。

提示
  • 只有群主有权转让群组。
  • 若在转让时选择了退出群组,转让成功后,群组内的所有成员会收到 Events.GROUP_OPERATION 事件,事件返回数据中 operation 操作类型值为 7,对应枚举 GroupOperation.TRANSFER_GROUP_OWNER
  • 退出成功后,群组内的所有成员会收到 Events.GROUP_OPERATION 事件,事件返回数据中 operation 操作类型值为 3,对应枚举 GroupOperation.QUIT
参数名类型必填描述
groupIdstring群组 ID。
newOwnerIdstring转让后的群主用户 ID。
quitGroupboolean转让后是否退出群组,默认值为 false。
configIQuitGroupConfig仅在 quitGrouptrue 时生效,控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config,默认在退出群组时会全部移除。
// 必填,群组 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 类型。

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

设置群组备注名

您可以调用 setGroupRemark 方法设置群组备注名。

当需要移除群组备注名时,remark 参数传 ''

参数名类型必填描述
groupIdstring群组 ID。
remarkstring群备注名。设置为 '' 代表移除。字符串长度不超过 64 个字符,如群备注名已存在则做替换处理,以最后一次设置为准。
提示
  1. 群组备注名只对用户当前用户生效。当群组中有新消息产生且该用户不在线时,推送标题将优先显示设置的群备注名。若用户未对该群设置备注名,则默认显示群名称。
  2. remark 不可以设置为纯空格。
const groupId = 'group001';
// 设置为 '' 代表移除。字符串长度不超过 64 个字符,如群备注名已存在则做替换处理,以最后一次设置为准
const remark = 'remark';
const res = await RongIMLib.setGroupRemark(groupId, remark);
// 需要输入存在的群组 ID,否则无法查询到群组信息,打印语句会抛异常
console.info('设置群组备注名结果', res);

查询群组备注名

您可以使用 getGroupsInfo 方法获取群组资料,其中包含有关 remark 信息。

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