加入群组管理

本文档指导您如何使用融云即时通讯（IM）Harmony IMLib SDK 实现主动加入群组、邀请用户加入群组、用户同意或拒绝加入群组、管理员同意或拒绝加群申请等功能。

提示

此功能从 1.8.0 版本开始支持。

开通服务

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

加入群组管理

加入群组管理包含：主动加入群组、邀请加入群组、 用户同意或拒绝加入群组、 管理员同意或拒绝加群申请等功能。

主动加入群组

调用 joinGroup 方法主动加入一个群组。

加入的结果受群组的加入权限 joinPermission 影响，有以下两种情况：

1. 群组的加入权限（joinPermission）为需要群主/管理员审批时，接口调用成功后 EngineError 会返回 GroupJoinGroupNeedManagerAccept ( 25424 )，表示需要等待群主或管理员的审批。同时本人和群主或管理员会都会收到 onGroupApplicationEvent 事件回调。
2. 群组的加入权限（joinPermission）为 “无需审批” 时，接口调用成功后 EngineError 会返回 Success ( 0 )，表示加入群组成功。同时本人和群内所有人会收到 onGroupOperation 事件回调，操作类型为 Join。

代码示例

TypeScript

// 群 Id
let groupId = "groupId";

IMEngine.getInstance().joinGroup(groupId).then(result => {
  if (EngineError.Success !== result.code) {
    // 加入群组请求失败
    return;
  }
  if (result.data) {
    // 加入群组请求成功时需要处理 processCode
    let ret: GroupResultWithProcessCode<void> = result.data;
    let processCode = ret.processCode;
  }
});

邀请他人加入群组

此功能的使用受群组邀请角色权限 invitePermission 的影响，有权限的用户才可以调用 inviteUsersToGroup 方法邀请他人加入群组。

代码示例

TypeScript

// 群 Id
let groupId = "groupId";
// 用户 ID 列表
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().inviteUsersToGroup(groupId, userIds).then(result => {
  if (EngineError.Success !== result.code) {
    // 邀请加入群组请求失败
    return;
  }
  if (result.data) {
    // 邀请加入群组请求成功需要处理 processCode
    let ret: GroupResultWithProcessCode<void> = result.data;
    let processCode = ret.processCode;
  }
});

邀请用户加入群组的行为受到以下三方面的影响：

1. 加入权限（joinPermission）：是否需要群主或管理员验证。
2. 邀请人角色（role）：邀请人是群主或管理员，还是普通用户。
3. 被邀请人处理权限（inviteHandlePermission）：是否需要被邀请人同意才能加入群组。

具体规则

提示

下表中默认了群组的邀请权限 invitePermission 为 Everyone，即所有人都可以邀请他人加入群组。

开发中可以根据实际情况设置不同的权限。

加入权限	邀请人角色	被邀请人审批	事件流程
需要群主/管理员审批	普通用户	需要	流程 A
		不需要	流程 B
	群主或管理员	需要	流程 C
		不需要	流程 D
无需群主/管理员审批	所有角色	需要	流程 C
		不需要	流程 D

事件流程如下

流程 A

权限描述： 普通用户邀请他人，需要群主/管理员审批，需要被邀请人审批。

1. 发出邀请后 EngineError 返回 GroupJoinGroupNeedManagerAccept(25424)，表示需要等待群主/管理员审批。邀请人和群主/管理员会收到 onGroupApplicationEvent 事件回调。
2. 群主/管理员同意后，邀请人、群主/管理员、被邀请人会收到 onGroupApplicationEvent 事件回调。
3. 被邀请人同意后，邀请人、群主/管理员、被邀请人会收到 onGroupApplicationEvent 事件回调。群内所有用户会收到群组操作 onGroupOperation 事件回调，操作类型为 Join。

流程 B

权限描述：

• 普通用户邀请他人，需要群主/管理员审批，不需要被邀请人审批。

1. 发出邀请后 EngineError 返回 GroupJoinGroupNeedManagerAccept(25424)，表示需要等待群主或管理员审批。邀请人和群主/管理员会收到 onGroupApplicationEvent 事件回调。
2. 群主或管理员同意后，被邀请人加入群组成功。邀请人、群主或管理员会收到 onGroupApplicationEvent 事件回调。群内所有用户会收到 onGroupOperation 事件回调，操作类型为 Join。

流程 C

权限描述：

• 任意角色的用户（群主、管理员或普通用户）邀请他人，无需群主/管理员审批，需要被邀请人审批。

1. 发出邀请后 EngineError 返回 GroupNeedInviteeAccept(25427)，表示需要被邀请人同意后才能进入群组。邀请人和被邀请人会收到 onGroupApplicationEvent 事件回调。
2. 被邀请人同意后，邀请人和被邀请人会收到 onGroupApplicationEvent 事件回调。群内所有用户会收到 onGroupOperation 事件回调，操作类型为 Join。

流程 D

权限描述：

• 群主/管理员邀请他人，需要群主/管理员审批，不需要被邀请人审批。
• 任意角色的用户（群主、管理员或普通用户）邀请他人，无需群主/管理员审批，不需要被邀请人审批。

1. 发出邀请后 EngineError 返回 Success(0)，表示邀请成功。被邀请人会直接加入群组，群内所有用户会收到 onGroupOperation 事件回调，操作类型为 Join。

用户处理入群邀请

同意入群邀请

用户在收到入群邀请后，可以调用 acceptGroupInvite 方法同意加入群组。

代码示例

TypeScript

// 群 ID
let groupId = "groupId";
// 发出邀请的用户 Id
let inviterId = "inviterId";

IMEngine.getInstance().acceptGroupInvite(groupId, inviterId).then(result => {
  if (EngineError.Success !== result.code) {
    // 用户同意加入群组失败
    return;
  }
  // 用户同意加入群组成功
});

拒绝入群邀请

用户在收到入群邀请后，可以调用 refuseGroupInvite 方法拒绝加入群组。

代码示例

TypeScript

// 群 Id
let groupId = "groupId";
// 发出邀请的用户 Id
let inviterId = "inviterId";
// 拒绝原因
let reason = "拒绝原因";

IMEngine.getInstance().refuseGroupInvite(groupId, inviterId, reason).then(result => {
  if (EngineError.Success !== result.code) {
    // 用户拒绝加入群组失败
  }
  // 用户拒绝加入群组成功
});

群主或管理员处理入群申请

群申请处理有效期为 7 天，融云服务端最多存储 7 天的申请数据，超过 7 天后需要重新发起申请。

同意入群申请

群主或管理员在收到入群申请后，可以调用 acceptGroupApplication 方法同意入群申请。

• 若处理的是用户主动加群申请，applicantId 传入群者 ID， inviterId 参数传 null 或空字符串 ""。
• 若处理的是邀请加群申请，applicantId 传入群者 ID， inviterId 传入邀请人 ID。
• 群申请处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。

代码示例

TypeScript

// 群 Id
let groupId = "groupId";
// 发出邀请的用户 Id
let inviterId = "inviterId";
// 申请入群用户 Id
let applicantId = "applicantId";

IMEngine.getInstance().acceptGroupApplication(groupId, inviterId, applicantId).then(result => {
  if (EngineError.Success !== result.code) {
    // 同意加入群组请求失败
    return;
  }
  if (result.data) {
    // 同意加入群组请求成功需要处理 processCode
    let ret: GroupResultWithProcessCode<void> = result.data;
    let processCode = ret.processCode;
  }
});

接口调用成功后 EngineError 受群组的被邀请人处理权限（[GroupInviteHandlePermission]）影响，会有以下两种情况：

1. 需要被邀请人同意时，EngineError 会返回 GroupNeedInviteeAccept(25427)，表示需要被邀请人同意后才能进入群组。被邀请人会收到 onGroupApplicationEvent 事件回调。
2. 无需被邀请人同意时，EngineError 会返回 Success(0)，表示被邀请者入群成功。群内所有用户会收到 onGroupOperation 加入群组类型事件回调。

拒绝入群申请

群主或管理员在收到入群申请后，可以调用 refuseGroupApplication 方法拒绝入群申请。

• 若处理的是用户主动加群申请，applicantId 传入群者 ID， inviterId 参数传 null 或空字符串 ""。
• 若处理的是邀请加群申请，applicantId 传入群者 ID， inviterId 传入邀请人 ID。
• 群申请处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";
// 发出邀请的用户 ID
let inviterId = "inviterId";
// 申请入群用户 ID
let applicantId = "applicantId";
// 拒绝原因
let reason = "拒绝原因";

IMEngine.getInstance().refuseGroupApplication(groupId, inviterId, applicantId, reason).then(result => {
  if (EngineError.Success !== result.code) {
    // 拒绝加入群组请求失败
    return;
  }
  // 拒绝加入群组请求成功
});

分页获取群申请列表

调用 getGroupApplications 方法分页获取群申请列表。群申请处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。

此接口不支持返回请求总数。

代码示例

TypeScript

let pageToken = null;
// 设置分页大小，取值范围为 [1~100]
let count = 10;
// 按操作时间正序、倒序获取。true：正序；false：倒序
let order = false;
// 分页获取
let paging_option = new PagingQueryOption(pageToken, count, order);

// 查询发出的申请 + 收到的申请类型的请求
let directionArray:Array<GroupApplicationDirection> = [GroupApplicationDirection.ApplicationSent, GroupApplicationDirection.ApplicationReceived];
// 查询管理员待处理 + 管理员拒绝 + 已加入类型的申请
let statusArray: Array<GroupApplicationStatus> = [GroupApplicationStatus.ManagerUnHandled, GroupApplicationStatus.ManagerRefused, GroupApplicationStatus.Joined];

IMEngine.getInstance().getGroupApplications(paging_option, directionArray, statusArray).then(result => {
  if (EngineError.Success !== result.code) {
    // 拉取失败
    return;
  }
  // 拉取成功
  if (result.data) {
    let data : PagingQueryResult<GroupApplicationInfo> = result.data;
    let pageToken: string = data?.pageToken;
    let totalCount: number = data?.totalCount;
    let infoArr: Array<GroupApplicationInfo> = Array.from(data?.data);
    // 使用返回的 pageToken 拉取下一页
  }
});