加入群组管理
本文档旨在指导开发者如何使用融云即时通讯 Web IMLib SDK 实现以下群组相关功能:
- 主动申请加入群组
- 邀请用户加入群组
- 用户处理入群邀请(同意或拒绝)
- 群组管理员处理入群申请(同意或拒绝)
- 分页获取群申请列表
该功能从 5.12.0 版本开始支持。
开通服务
使用此功能前,您须在融云控制台开通信息托管服务。
用户申请或邀请事件及结果回调
用户可以通过主动调用 joinGroup 接口申请加入群组,或由群内成员调用 inviteUsersToGroup 接口邀请用户加入群组。相关的申请或邀请事件及其处理结果可通过 Events.GROUP_APPLICATION_EVENT
事件监听,返回的数据类型为 IGroupApplicationInfo。
示例代码
RongIMLib.addEventListener(Events.GROUP_APPLICATION_EVENT, (data) => {
console.log('用户申请或邀请事件及结果回调', data);
});
加入群组管理
加入群组管理包括:主动加入群组、邀请他人加入群组、用户处理入群邀请、群主或管理员处理入群申请等功能。
主动加入群组
您可以调用 joinGroup 方法主动申请加入指定群组。
接口调用结果受群组的 GroupJoinPermission 权限设置影响,具体如下:
-
需要群主或管理员审批: 接口调用成功后,
processCode
返回 25424,表示需等待群主或管理员审批。申请用户及群主或管理员将收到 Events.GROUP_APPLICATION_EVENT 事件回调。 -
无需审批:接口调用成功后,
processCode
返回 0,表示成功加入群组。申请用户及群内所有成员将收到 Events.GROUP_OPERATION 事件回调,事件中的 operation=1(GroupOperation.JOIN)。 -
不允许任何人加入:无法通过 joinGroup 接口加入群组。
接口
RongIMLib.joinGroup(groupId)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
示例代码
// 必填,最大长度 64 个字符。支持大小写英文字母与数字的组合
const groupId = 'group001';
const res = await RongIMLib.joinGroup(groupId);
console.info('加入群组结果', res);
邀请他人加入群组
邀请他人加入群组的操作受群组邀请权限 GroupOperationPermission 控制,只有具有相应权限的用户才能发起邀请。
具有邀请权限的用户可调用 inviteUsersToGroup 方法邀请他人加入群组。
接口
RongIMLib.inviteUsersToGroup(groupId, userIds)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
userIds | string[] | 是 | 用户 ID 数组,最多支持 30 个用户。 |
示例代码
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,最多支持 30 个用户
const res = await RongIMLib.inviteUsersToGroup(groupId, userIds);
console.info('邀请用户加入群组结果', res);
邀请流程受以下因素影响:
- 加入权限( GroupJoinPermission ):是否需要群主或管理员审批。
- 邀请人角色( GroupOperationPermission ):邀请人是群主或管理员,还是普通用户。
- 被邀请人处理权限( GroupInviteHandlePermission ):是否需要被邀请人同意才能加入群组。
邀请规则
下表中默认了群组的邀请权限 GroupOperationPermission 为 Everyone
,即所有人都可以邀请他人加入群组。
开发中可以根据实际情况设置不同的权限。
加入权限 | 邀请人角色 | 被邀请人审批 | 事件流程 |
---|---|---|---|
需要群主/管理员审批 | 普通用户 | 需要 | 流程 A |
不需要 | 流程 B | ||
群主或管理员 | 需要 | 流程 C | |
不需要 | 流程 D | ||
无需群主/管理员审批 | 所有角色 | 需要 | 流程 C |
不需要 | 流程 D |
事件流程如下
流程 A
普通用户邀请他人,需要群主/管理员审批,需要被邀请人审批。
- 发出邀请后,成功回调的
code
返回 25424,表示需要等待群主/管理员审批。邀请人和群主/管理员会收到Events.GROUP_APPLICATION_EVENT
事件回调。 - 群主/管理员同意后,邀请人、群主/管理员、被邀请人会收到
Events.GROUP_APPLICATION_EVENT
事件回调。 - 被邀请人同意后,邀请人、群主/管理员、被邀请人会收到
Events.GROUP_APPLICATION_EVENT
事件回调。群内所有用户会收到群组操作Events.GROUP_OPERATION
事件回调,事件返回数据中operation
操作类型值为 1,对应枚举GroupOperation.JOIN
。
流程 B
- 普通用户邀请他人,需要群主/管理员审批,不需要被邀请人审批。
- 发出邀请后,成功回调的
code
返回 25424,表示需要等待群主或管理员审批。邀请人和群主/管理员会收到Events.GROUP_APPLICATION_EVENT
事件回调。 - 群主或管理员同意后,被邀请人加入群组成功。邀请人、群主或管理员会收到
Events.GROUP_APPLICATION_EVENT
事件回调。群内所有用户会收到Events.GROUP_OPERATION
事件回调,事件返回数据中operation
操作类型值为 1, 对应枚举GroupOperation.JOIN
。
流程 C
- 任意角色用户邀请他人,无需群主/管理员审批,需要被邀请人审批。
- 发出邀请后,成功回调的
code
返回 25427,表示需要被邀请人同意后才能进入群组。邀请人和被邀请人会收到Events.GROUP_APPLICATION_EVENT
事件回调。 - 被邀请人同意后,邀请人和被邀请人会收到
Events.GROUP_APPLICATION_EVENT
事件回调。群内所有用户会收到Events.GROUP_OPERATION
事件回调,事件返回数据中operation
操作类型值为 1,对应枚举GroupOperation.JOIN
。
流程 D
- 群主/管理员邀请他人,需要群主/管理员审批,不需要被邀请人审批。
- 任意角色用户邀请他人,无需群主/管理员审批,不需要被邀请人审批。
- 发出邀请后,成功回调的
code
返回 0,表示邀请成功。被邀请人会直接加入群组,群内所有用户会收到Events.GROUP_OPERATION
事件回调,事件返回数据中operation
操作类型值为 1,对应枚举GroupOperation.JOIN
。
用户处理入群邀请
同 意入群邀请
当用户收到入群邀请时,可调用 acceptGroupInvite 方法同意加入指定群组。
接口
RongIMLib.acceptGroupInvite(groupId, inviterId)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID |
inviterId | string | 是 | 发出邀请的用户 ID |
示例代码
const groupId = 'group001'; // 群组 ID
const inviterId = 'inviterId'; // 发出邀请的用户 ID
const res = await RongIMLib.acceptGroupInvite(groupId, inviterId);
console.info('同意加入群组结果', res);
拒绝入群邀请
当用户收到入群邀请时,可调用 refuseGroupInvite 方法拒绝加入群组。
接口
RongIMLib.refuseGroupInvite(groupId, inviterId, reason)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID |
inviterId | string | 是 | 发出邀请的用户 ID |
reason | string | 否 | 备注内容,拒绝时可选择是否输入拒绝原因,内容不超过 128 个字符 |
示例代码
const groupId = 'group001'; // 群组 ID
const inviterId = 'inviterId'; // 发出邀请的用户 ID
const reason = '不感兴趣'; // 非必填,拒绝原因
const res = await RongIMLib.refuseGroupInvite(groupId, inviterId, reason);
console.info('拒绝加入群组结果', res);
群主或管理员处理入群申请
同意入群申请
群主或管理员收到入群申请后,可调用 acceptGroupApplication 方法同意用户入群。
接口
RongIMLib.acceptGroupApplication(groupId, applicantId, inviterId)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID |
applicantId | string | 是 | 申请入群用户 ID |
inviterId | string | 否 | 邀请人 ID。非必填,如果是邀请入群,则传邀请人ID;主动申请加群可省略 |
- 若处理的是用户主动加群申请,
applicantId
传入群者 ID,inviterId
参数不传或空字符串''
。 - 若处理的是邀请加群申请,
applicantId
传入群者 ID,inviterId
传入邀请人 ID。
示例代码
const groupId = 'group001'; // 群组 ID
const applicantId = 'applicantId'; // 入群者 ID
const res = await RongIMLib.acceptGroupApplication(groupId, applicantId);
console.info('同意用户加入群组结果', res);
接口返回的 code 受群组邀请权限(GroupInviteHandlePermission)控制,情况如下:
- 需要被邀请人同意:返回 25427,表示还需申请人确认,被邀请人将收到 Events.GROUP_APPLICATION_EVENT 事件回调
- 无需被邀请人同意:返回 0,表示申请成功,群内成员会收到 Events.GROUP_OPERATION 的“加入群组”事件通知
拒绝入群申请
群主或管理员收到入群申请后,可调用 refuseGroupApplication 方法拒绝该请求。
接口
RongIMLib.refuseGroupApplication(groupId, applicantId, inviterId, reason)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID |
applicantId | string | 是 | 申请入群用户 ID |
inviterId | string | 否 | 邀请人 ID。非必填,如果是邀请入群,则传邀请人ID;如果是主动加群,可以为空。 |
reason | string | 否 | 拒绝原因,非必填,最多 128 字符 |
- 若处理的是用户主动加群申请,
applicantId
传入群者 ID,inviterId
参数不传或空字符串''
。 - 若处理的是邀请加群申请,
applicantId
传入群者 ID,inviterId
传入邀请人 ID。
示例代码
const groupId = 'group001'; // 群组 ID
const applicantId = 'applicantId'; // 申请入群用户 ID
const inviterId = 'inviterId'; // 非必填,主动申请加入邀请人 ID 传递 '' 或者 undefined
const reason = '不符合群组要求'; // 非必填,拒绝原因
const res = await RongIMLib.refuseGroupApplication(groupId, applicantId, inviterId, reason);
console.info('拒绝用户加入群组结果', res);
分页获取群申请列表
调用 getGroupApplications 方法,分页查询当前群组的申请记录。
- 申请记录有效期为 7 天,超过 7 天数据会自动清除,需重新发起申请。
- Web 平台返回的 IPagingQueryResult 结构暂不包含
totalCount
字段
接口
RongIMLib.getGroupApplications(option, directions, status)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
option | IPagingQueryOption | 是 | 分页参数,单页最多拉取 200 条记录 |
directions | GroupApplicationDirection | 否 | 群申请方向,仅 Electron 支持 |
status | GroupApplicationStatus | 否 | 群申请状态,仅 Electron 支持 |
示例代码 |
const option = {
// 必填,范围 1 ~ 200
count: 50,
}
const directions = [GroupApplicationDirection.ApplicationSent]; // 群组请求方向数组
const status = [GroupApplicationStatus.JoinUnHandled]; // 群组请求状态数组
const res = await RongIMLib.getGroupApplications(option, directions, status);
console.info('获取群组请求结果', res);