文档中心
即时通讯
群组相关
群组管理

群组管理

更新时间：2024-10-15 23:28

功能简介

ZIM SDK 提供了群组管理功能，支持用户创建/解散群组、加入/退出群组，持久化维系群组关系。

群组管理功能可应用于办公群、社交群、兴趣群以及粉丝群等场景中，群组成员数量上限请参考计费说明。

前提条件

在实现“群组管理”功能之前，请确保：

已在 ZEGO 控制台创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台自助开通 ZIM 服务（详情请参考控制台的服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
已集成 ZIM SDK，详情请参考快速开始 - 实现基本收发消息的 “2 集成 SDK”。

创建群组

客户端 A 登录 ZIM SDK 后，调用 createGroup 接口，设置高级配置，创建一个群组，此时 A 就是 群主；其他客户端可以根据 A 创建的群组 groupID 加入群组。

开发者可以通过 ZIMGroupCreatedCallback，判断群组是否创建成功。相关错误码请查看常见错误码。

“groupID” 支持开发者自定义规则生成，仅支持数字，英文字符和 '!'、'#'、'$'、'%'、'&'、'('、')'、'+'、'-'、':'、';'、'<'、'='、'.'、'>'、'?'、'@'、'['、']'、'^'、'_'、'{'、'}'、'|'、'~'，且不能以 ’#‘ 开头；若该字段为空，ZIM 服务器会自动生成。建议开发者将 “groupID” 设置为一个有意义的值，可将其与自己的业务账号系统进行关联。
调用 createGroup 接口创建群组后，会直接加入群组，无需再调用 joinGroup 接口加入群组。
用户创建群组时，该用户即是该群组的“群主”。如果想要转让身份，请参考转让群主。
如需规定群组人数上限，以及入群模式（包括验证模式、邀请模式和被邀请人是否需要同意），请集成 2.15.0 或以上版本的 SDK。

// 创建一个群组
// groupID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'，且不能以 ’#‘ 开头。
// groupName 最大 50 字节的字符串，无特殊字符限制。
ZIMGroupInfo *groupInfo = [[ZIMGroupInfo alloc] init];
groupInfo.groupID = @"groupID";
groupInfo.groupName = @"groupName";
groupInfo.groupAvatarUrl = @"groupAvatarUrl";

ZIMGroupAdvancedConfig *advancedConfig = [[ZIMGroupAdvancedConfig alloc] init];
// 主动加群验证模式
advancedConfig.joinMode = ZIMGroupJoinModeAny;
// 邀请进群验证模式
advancedConfig.inviteMode = ZIMGroupInviteModeAny;
// 被邀请入群验证模式
advancedConfig.beInviteMode = ZIMGroupBeInviteModeNone;

//成员数量限制
advancedConfig.maxMemberCount = 300;

[[ZIM getInstance] createGroup:groupInfo userIDs:@[@"userID1",@"userID2"] config:advancedConfig callback:^(ZIMGroupFullInfo * _Nonnull groupInfo, NSArray<ZIMGroupMemberInfo *> * _Nonnull userList, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
    //这里写创建群组后的业务逻辑
}];

加入群组

如需用户加入群组后自动获取群历史消息，请联系 ZEGO 技术支持进行配置。

其他用户登录 ZIM SDK 后，可以通过主动加入或被邀请加入由 A 创建的群组。

如果用户加入成功后，全体群成员（包括该新成员）都会收到 groupMemberStateChanged 和 groupStateChanged 的回调通知：

- (void)zim:(ZIM *)zim
    groupMemberStateChanged:(ZIMGroupMemberState)state
                      event:(ZIMGroupMemberEvent)event
                   userList:(NSArray<ZIMGroupMemberInfo *> *)userList
               operatedInfo:(ZIMGroupOperatedInfo *)operatedInfo
    groupID:(NSString *)groupID{
}
- (void)zim:(ZIM *)zim
    groupStateChanged:(ZIMGroupState)state
                event:(ZIMGroupEvent)event
         operatedInfo:(ZIMGroupOperatedInfo *)operatedInfo
  groupInfo:(ZIMGroupFullInfo *)groupInfo{
}

方式 1：主动加入群组

根据群组的 joinMode，外部用户需要选择相应的接口加入群组。

当 joinMode 为 0（ZIMGroupJoinModeAny），用户调用 joinGroup 接口，传入 groupID（groupID 必须已经存在，否则会操作失败），即可直接加入群组。

// 其他客户端直接加入群组
[zim joinGroup:GroupID callback:^(ZIMGroupFullInfo * _Nonnull groupInfo, ZIMError * _Nonnull errorInfo) {
    //这里写调用加入群组接口后的业务逻辑
}];

当 joinMode 为 1（ZIMGroupJoinModeAuth）时：

用户调用 sendGroupJoinApplicationToGroupID 接口发起申请。

ZIMGroupJoinApplicationSendConfig *config = [[ZIMGroupJoinApplicationSendConfig alloc] init];
config.wording = @"请让我进群";
[zim sendGroupJoinApplicationToGroupID:groupID config:config callback:^(NSString * _Nonnull groupID, ZIMError *errorInfo) {        
     // 发送群申请结果回调     
}];

群主或管理员通过监听 groupApplicationListChanged 事件，得知新增申请待处理。

// 监听 groupApplicationListChanged 事件
- (void)zim:(ZIM *)zim
groupApplicationListChanged:(NSArray<ZIMGroupApplicationInfo *> *)applicationList
     action:(ZIMGroupApplicationListChangeAction)action{
}

群主或管理员审批

群主或管理员调用 acceptGroupJoinApplicationFromUserID 接口，同意用户入群，用户成功入群。

// 同意申请
[zim acceptGroupJoinApplicationFromUserID:userID groupID:groupID config:config callback:^(NSString * _Nonnull groupID, NSString * _Nonnull userID, ZIMError * _Nonnull errorInfo) {
        // 同意申请结果回调
}];

群主或管理员调用 rejectGroupJoinApplicationFromUserID 接口，拒绝用户入群。

// 否决申请
[zim rejectGroupJoinApplicationFromUserID:userID groupID:groupID config:config callback:^(NSString * _Nonnull groupID, NSString * _Nonnull userID, ZIMError * _Nonnull errorInfo) {
    // 否决申请结果回调
}];

入群申请人、群主、管理员和接口调用者会收到 groupApplicationUpdated 回调通知。

// 监听 groupApplicationUpdated 事件
- (void)zim:(ZIM *)zim groupApplicationUpdated:(NSArray<ZIMGroupApplicationInfo *> *)applicationList{

}

方式 2：由群内成员添加入群组（邀请入群）

群内用户可通过以下任意接口邀请用户入群：

请确认被邀请用户（以下称为“目标用户”）已通过 loginWithUserID 接口登录注册过，否则会操作失败。
- inviteUsersIntoGroup：直接邀请用户入群。
```
// 由群内成员添加入群组
[zim inviteUsersIntoGroup:userIDs groupID:groupID callback:^(NSArray<ZIMGroupMemberInfo *> * _Nonnull userList, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
    //这里写调用邀请入群接口后的业务逻辑
}];
```
  群内成员调用 inviteUsersIntoGroup 接口，邀请其他用户加入群组时：
  - 被添加的用户将直接进入群组，无需同意。
  - 被添加的用户 userID，必须是真实存在的（即已经通过 loginWithUserInfo 接口登录注册过），否则会操作失败。

sendGroupInviteApplicationsToUserIDs：向用户发起入群邀请申请。

// 发送邀请入群申请
ZIMGroupInviteApplicationSendConfig *config = [[ZIMGroupInviteApplicationSendConfig alloc] init];
config.wording = @"xxx邀请你加入群聊";
[zim sendGroupInviteApplicationsToUserIDs:@[@"userID1",@"userID2"] groupID:@"groupID" config:config callback:^(NSString * _Nonnull groupID, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {

}];

根据群组的 inviteMode 和 beInviteMode，以及调用用户的群组角色，接口调用效果如下表所示：

beInviteMode	inviteMode	调用接口	调用角色	结果
0：None	0：Any	inviteUsersIntoGroup	所有群成员	被邀请人自动成为群成员。
	0：Any	sendGroupInviteApplicationsToUserIDs	所有群成员	被邀请人自动成为群成员，且不产生邀请入群申请记录。
	1：Admin	inviteUsersIntoGroup	普通成员	失败。
		inviteUsersIntoGroup	群主或管理员	被邀请人自动成为群成员。
		sendGroupInviteApplicationsToUserIDs	普通成员	失败。
		sendGroupInviteApplicationsToUserIDs	群主或管理员	被邀请人自动成为群成员，且不产生邀请入群申请记录。
1：Auth	0：Any	inviteUsersIntoGroup	所有群成员	产生邀请入群申请记录，等待目标用户做出反应。
	0：Any	sendGroupInviteApplicationsToUserIDs	所有群成员	产生邀请入群申请记录，等待目标用户做出反应。此外，如果调用者为群主或管理员时，会收到 groupApplicationListChanged。
	1：Admin	inviteUsersIntoGroup	普通成员	失败。
		inviteUsersIntoGroup	群主或管理员	产生邀请入群申请记录，等待目标用户做出反应。
		sendGrsendGroupInviteApplicationsToUserIDsoupInviteApplications	普通成员	失败。
			群主或管理员	产生邀请入群申请记录，等待目标用户做出反应。此外，如果调用者为群主或管理员时，会收到 groupApplicationListChanged。

beInviteMode 为 1（ZIMGroupBeInviteModeAuth）时，目标用户和邀请人（仅当接口调用人为群主和群管理员时）会通过 groupApplicationListChanged 收到回调通知。目标用户需要审批该申请。

目标用户调用 acceptGroupInviteApplicationFromInviterUserID 接口，同意入群，成为群成员。

[zim acceptGroupInviteApplicationFromInviterUserID:inviterUserID groupID:groupID config:config callback:^(ZIMGroupFullInfo * _Nonnull groupInfo, NSString * _Nonnull inviterUserID, ZIMError * _Nonnull errorInfo) {

}];

目标用户调用 rejectGroupInviteApplicationFromInviterUserID 接口，拒绝入群。

[zim rejectGroupInviteApplicationFromInviterUserID:inviterUserID groupID:groupID config:config callback:^(NSString * _Nonnull groupID, NSString * _Nonnull inviterUserID, ZIMError * _Nonnull errorInfo) {

}];

beInviteMode 为 1（ZIMGroupBeInviteModeAuth）时，该用户和邀请人（仅当接口调用人为群主和群管理员时）会通过 groupApplicationUpdated 收到回调通知上述审批事件。
```
- (void)zim:(ZIM *)zim groupApplicationUpdated:(NSArray<ZIMGroupApplicationInfo *> *)applicationList{

}
```

退出群组

成员退出群组也存在两种方式（二选一），主动退出和被提出群组。

用户退出群组后，不会清除本地的会话列表，还可以看到退出之前的群内聊天记录。

方式 1：主动退出群组

成员登录 ZIM SDK 后，直接调用 leaveGroup 接口，传入 groupID（groupID 必须已经存在，否则会操作失败），主动退出群组。退出成功后，全体群成员都会收到 groupMemberStateChanged 的回调通知。

群主退出群组时，群主身份将自动转让给加入本群组最早的那个成员；所有成员退出群组时，群组自动解散。

// 主动退出群组
[zim leaveGroup:groupID callback:^(ZIMError * _Nonnull errorInfo) {
        //这里写调用离开群组接口后的业务逻辑
}];

方式 2：群主移除群内成员

群主调用 kickGroupMembers 接口，传入 groupID（groupID 必须已经存在，否则会操作失败）、userIDList（需要被移除的成员列表），移除这些成员。移除成功后，全体群成员（包括群主自己、被移除的成员）都会收到 groupMemberStateChanged 的回调通知。

只有群主和管理员可以调用 kickGroupMembers 接口，移除群内成员；且移除成员时，该成员无需登录在线，也无需经过该成员同意，即可直接移除。
被移除的用户 userID，必须是存在于本群组的成员列表内，否则会操作失败。

// 群主移除群内成员
[zim kickGroupMembers:userIDs groupID:groupID callback:^(NSArray<NSString *> * _Nonnull kickedUserIDList, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
        //这里写调用群主移除群内成员接口后的业务逻辑 
}];

解散群组

群主登录 ZIM SDK 后，如果想要解散群组，可以通过 dismissGroup 接口，解散群组。解散群组成功后，全体群成员都会收到 groupStateChanged 回调通知。

只有群主才能调用 dismissGroup 接口，解散群组。
所有成员退出群组时，群组将自动解散。
群组解散后，不会清除本地的会话列表，用户还可以看到退出之前的群内聊天记录。

// 群主解散群组
[zim dismissGroup:groupID callback:^(ZIMError * _Nonnull errorInfo) {
        // 这里写调用解散群接口后的业务代码
 }];

更多功能

查询已加入群组列表

用户登录 ZIM SDK 后，如果想要了解自己加入了哪些群组，可以通过 queryGroupList 接口，获取自己已加入的群组列表。

// 用户查询自己加入了哪些群组
[zim queryGroupListByGroupID:^(NSArray<ZIMGroupInfo *> * _Nonnull groupList, ZIMError * _Nonnull errorInfo) {
    //这里写调用查询群列表接口后的业务代码
}];

搜索已加入群组

用户登录 ZIM SDK 后，如果想要根据条件对已加入的群组进行搜索，可以调用 searchLocalGroupsWithConfig 接口，传入 config、callback 搜索群组。

搜索结果将通过 ZIMGroupsSearchedCallback 回调接口返回。

// 搜索名称中包含 “zego” 的已加入群组
ZIMGroupSearchConfig *config = [[ZIMGroupSearchConfig alloc] init];
config.count = 10;
config.nextFlag = 0;
config.isAlsoMatchGroupMemberNickname = true; // 如果群成员昵称包含 “zego”，搜索结果将包含该群组
config.isAlsoMatchGroupMemberUserName = true; // 如果群成员用户名称包含 “zego”，搜索结果将包含该群组
config.keywords = @[@"zego"];
[[ZIM getInstance] searchLocalGroupsWithConfig:config callback:^(NSArray<ZIMGroupSearchInfo *> * _Nonnull groupSearchInfoList, unsigned int nextFlag, ZIMError * _Nonnull errorInfo) {
    if(errorInfo.code == ZIMErrorCodeSuccess){
        // 开发者可从 groupSearchInfoList 中获取到群组信息
    }else{
        // 根据官网错误码表处理
    }
}];

禁言或解禁群组

禁言，是指让群组会话内的用户不能发言。

在登录 ZIM SDK 后，用户可以禁言自己管理的群组。只需调用 muteGroup 接口，传入相应参数设置群组 ID、禁言模式、持续时长和目标角色，即可禁言或解禁群组。

ZIM 支持 3 种群组禁言模式：

所有群组成员不能发言；
所有普通群组成员（role 为 3）不能发言，；
指定角色的群成员不能发言。

禁言操作结果将通过 ZIMGroupMutedCallback 回调接口返回。

// 设置群组禁言配置
ZIMGroupMuteConfig *muteConfig = [[ZIMGroupMuteConfig alloc] init];
// 群组禁言模式为指定角色的群成员不能发言
muteConfig.mode = ZIMGroupMuteModeCustom;
// 禁言时长为 30 秒
muteConfig.duration = 30;
// 角色为 3 和 5 的群成员被禁言
muteConfig.roles = @[@3,@5];

[[ZIM getInstance] muteGroup:YES groupID:@"groupID" config:muteConfig callback:^(NSString * _Nonnull groupID, BOOL isMute, ZIMGroupMuteInfo * _Nonnull info, ZIMError * _Nonnull errorInfo) {
    // 开发者可从 info 中获取到群组禁言信息
}];

群组禁言或解禁成功后，全部群成员会收到 groupMutedInfoUpdated，得知哪些角色无法在该群组发言或可恢复发言。


- (void)zim:(ZIM *)zim
    groupMutedInfoUpdated:(ZIMGroupMuteInfo *)muteInfo
            operatedInfo:(ZIMGroupOperatedInfo *)operatedInfo
                 groupID:(NSString *)groupID{
    // 通过继承 ZIMEventHandler 的方式，在这里监听群禁言状态变更的信息，并进行相应处理
}

如果您希望禁止特定群组成员发言，请参考群成员管理 - 设置群成员禁言状态。

确认群组会话是否可用

如需确认当前用户是否仍在所加入的群组会话中，请通过以下任意方法：

参考会话管理 - 拉取会话列表主动拉取会话列表。
参考会话管理 - 更新会话列表，监听会话变更回调，更新会话列表。

当会话类型是群类型时，从返回结果中的 ZIMGroupConversation 获取 isDisabled，即会话是否可用。

isDisabled 值说明如下：

为 true 时，表示当前用户不在该群组会话。当前用户主动退出、被踢或群组解散都会导致会话不可用。
为 false 时，表示当前用户在该群组会话。

更新入群验证模式

群主和管理员登录 ZIM SDK 后，可以通过 updateGroupJoinMode 接口更新入群验证模式。

更新成功后，全体群成员都会收到 groupVerifyInfoUpdated 回调通知。

// 监听 groupVerifyInfoUpdated 事件
- (void)zim:(ZIM *)zim
    groupVerifyInfoUpdated:(ZIMGroupVerifyInfo *)verifyInfo
            operatedInfo:(ZIMGroupOperatedInfo *)operatedInfo
    groupID:(NSString *)groupID{

}

// 更新入群验证模式
[zim updateGroupJoinMode:ZIMGroupJoinModeAuth groupID:@"groupID" callback:^(NSString * _Nonnull groupID, ZIMGroupJoinMode mode, ZIMError * _Nonnull errorInfo) {

}];

更新邀请模式

群主和管理员登录 ZIM SDK 后，可以通过 updateGroupInviteMode 接口更新邀请模式。

更新成功后，全体群成员都会收到 groupVerifyInfoUpdated 回调通知。

// 监听 onGroupVerifyInfoUpdated 事件
- (void)zim:(ZIM *)zim
    groupVerifyInfoUpdated:(ZIMGroupVerifyInfo *)verifyInfo
              operatedInfo:(ZIMGroupOperatedInfo *)operatedInfo
    groupID:(NSString *)groupID{

}

// 更新邀请模式
[zim updateGroupInviteMode:ZIMGroupInviteModeNone groupID:@"groupID" callback:^(NSString * _Nonnull groupID, ZIMGroupInviteMode mode, ZIMError * _Nonnull errorInfo) {

}];

更新邀请目标用户验证模式

群主和管理员登录 ZIM SDK 后，可以通过 updateGroupBeInviteMode 接口更新目标用户验证模式。

更新成功后，全体群成员都会收到 groupVerifyInfoUpdated 回调通知。

// 监听 onGroupVerifyInfoUpdated 事件
- (void)zim:(ZIM *)zim
    groupVerifyInfoUpdated:(ZIMGroupVerifyInfo *)verifyInfo
              operatedInfo:(ZIMGroupOperatedInfo *)operatedInfo
    groupID:(NSString *)groupID{

    }

// 更新目标用户验证模式
  [zim updateGroupBeInviteMode:ZIMGroupBeInviteModeAuth groupID:@"groupID" callback:^(NSString * _Nonnull groupID, ZIMGroupBeInviteMode mode, ZIMError * _Nonnull errorInfo) {

  }];

查询入群申请列表

用户登录 ZIM SDK 后，调用 queryGroupApplicationListWithConfig 接口，可以查询入群申请列表，查询结果包含自己的入群申请和自己被邀请入群的申请。当用户是群主或管理员时，查询结果还会包含他人的入群申请和自己邀请他人入群的申请。

ZIMGroupApplicationListQueryConfig *config = [[ZIMGroupApplicationListQueryConfig alloc] init];
config.count = 20;
[zim queryGroupApplicationListWithConfig:config callback:^(NSArray<ZIMGroupApplicationInfo *> * _Nonnull applicationList, unsigned int nextFlag, ZIMError * _Nonnull errorInfo) {

}];