群组管理

---

功能简介

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

ZIMGroupAdvancedConfig config = new ZIMGroupAdvancedConfig();
HashMap<String, String> attributes = new HashMap<>();
attributes.put("key_0", "value_0");
attributes.put("key_1", "value_1");
attributes.put("key_2", "value_2");
config.groupAttributes = attributes;
// 主动加群验证模式
config.joinMode = ZIMGroupJoinMode.ANY;
// 邀请进群验证模式
config.inviteMode = ZIMGroupInviteMode.ANY;
// 被邀请入群验证模式
config.beInviteMode = ZIMGroupBeInviteMode.NONE;
// 成员数量限制
config.maxMemberCount = 300;

ArrayList<String> userList = new ArrayList<>();
userList.add("user_1");
userList.add("user_2");

zim.createGroup(groupInfo, userList, config, new ZIMGroupCreatedCallback() {
    @Override
    public void onGroupCreated(ZIMGroupFullInfo groupInfo, ArrayList<ZIMGroupMemberInfo> userIDs, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        // 通过 errorInfo.code 获取创建群的结果
    }
});

加入群组

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

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

// 监听 onGroupMemberStateChanged 和 onGroupStateChanged
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupMemberStateChanged(ZIM zim, ZIMGroupMemberState state, ZIMGroupMemberEvent event, ArrayList<ZIMGroupMemberInfo> userList, ZIMGroupOperatedInfo operatedInfo, String groupID) {
          // 群成员状态变化回调通知
    }

    public void onGroupStateChanged(ZIM zim, ZIMGroupState state, ZIMGroupEvent event, ZIMGroupOperatedInfo operatedInfo, ZIMGroupFullInfo groupInfo) {
          // 群状态变化回调通知
    }

});

方式 1：主动加入群组

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

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

  // 其他客户端直接加入群组
  zim.joinGroup("groupID", new ZIMGroupJoinedCallback() {
      @Override
      public void onGroupJoined(ZIMGroupFullInfo groupInfo, ZIMError errorInfo) {
          // 通过 errorInfo.code 获取加入群组的结果
      }
  });

• 当 joinMode 为 1（AUTH）时：

  1. 用户调用 sendGroupJoinApplication 接口发起申请。

     ZIMGroupJoinApplicationSendConfig config = new ZIMGroupJoinApplicationSendConfig();
     config.wording = "请让我进群";
     zim.sendGroupJoinApplication("groupID", config, new ZIMGroupJoinApplicationSentCallback() {
         @Override
         public void onGroupJoinApplicationSent(String groupID, ZIMError errorInfo){
             // 发送群申请结果回调
         }
     });

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

     // 监听 ongGoupApplicationListChanged 事件
     zim.setEventHandler(new ZIMEventHandler(){
         public void onGroupApplicationListChanged(ZIM zim, ArrayList<ZIMGroupApplicationInfo> applicationList, ZIMGroupApplicationListChangeAction action) {
         // 群申请列表更新回调通知
         }
     });

  3. 群主或管理员审批

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

       // 同意申请
       ZIMGroupJoinApplicationAcceptConfig config = new ZIMGroupJoinApplicationAcceptConfig();
       zim.acceptGroupJoinApplication("userID", "groupID", config, new ZIMGroupJoinApplicationAcceptedCallback(){
           public void onGroupJoinApplicationAccepted(String groupID, String userID, ZIMError errorInfo){
               // 同意申请结果回调
           };
       });

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

       // 否决申请
       ZIMGroupJoinApplicationRejectConfig config = new ZIMGroupJoinApplicationRejectConfig();
       zim.rejectGroupJoinApplication("userID", "groupID", config, new ZIMGroupJoinApplicationRejectedCallback(){
           public void onGroupJoinApplicationRejected(String groupID, String userID, ZIMError errorInfo) {
               // 拒绝用户入群结果回调  
           }
       });

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

     // 监听 onGroupApplicationUpdated 事件
     zim.setEventHandler(new ZIMEventHandler(){
             public void onGroupApplicationUpdated(ZIM zim, ArrayList<ZIMGroupApplicationInfo> applicationList){
             //  群申请信息更新回调
             }
     });

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

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

   请确认被邀请用户（以下称为“目标用户”）已通过 login 接口登录注册过，否则会操作失败。

   • inviteUsersIntoGroup：直接邀请用户入群，无需对方同意。

     // 由群内成员添加入群组
     ArrayList<String> userList = new ArrayList<>();
     userList.add("user_1");
     userList.add("user_2");
     zim.inviteUsersIntoGroup(userList, "group_id", new ZIMGroupUsersInvitedCallback() {
         @Override
         public void onGroupUsersInvited(ArrayList<ZIMGroupMemberInfo> userList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
             // 通过 errorInfo.code 获取添加入群组的结果    
         }
     });

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

     // 发送邀请入群申请
     ZIMGroupInviteApplicationSendConfig config = new ZIMGroupInviteApplicationSendConfig();
     config.wording = "请加入我的群吧";
     List<String> userIDs = new ArrList<String>();
     userIDs.add("user1");
     userIDs.add("user2");
     zim.sendGroupInviteApplications(userIDs, "groupID", config, new ZIMGroupInviteApplicationsSentCallback(){
         public void onGroupInviteApplicationsSent(String groupID, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo){
             // 发起群邀请结果回调
         }
     });

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

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

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

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

     // 同意邀请入群申请
     ZIMGroupInviteApplicationAcceptConfig config = new ZIMGroupInviteApplicationAcceptConfig();
     zim.acceptGroupInviteApplication("inviterUserID", "groupID", config, new ZIMGroupInviteApplicationAcceptedCallback(){
     
         public void onGroupInviteApplicationAccepted(ZIMGroupFullInfo groupInfo, String inviterUserID, ZIMError errorInfo){
             // 同意群邀请结果回调
         }
     });

   • 目标用户调用 rejectGroupInviteApplication 接口，拒绝入群邀请。

     // 拒绝邀请入群申请
     ZIMGroupInviteApplicationRejectConfig config = new ZIMGroupInviteApplicationRejectConfig();
     zim.rejectGroupInviteApplication("inviterUserID", "groupID", config, new ZIMGroupInviteApplicationRejectedCallback(){
         public void onGroupInviteApplicationRejected(String groupID, String inviterUserID, ZIMError errorInfo) {
                 //  拒绝群邀请结果回调
         }
     });

3. beInviteMode 为 1（AUTH）时，该用户和邀请人（仅当接口调用人为群主和群管理员时）会通过 onGroupApplicationUpdated 收到回调通知上述审批事件。

   zim.setEventHandler(new ZIMEventHandler(){
       public void onGroupApplicationUpdated(ZIM zim,
                                           ArrayList<ZIMGroupApplicationInfo> applicationList) {
               // 群申请更新回调通知
        }
   });

退出群组

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

方式 1：主动退出群组

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

// 主动退出群组
zim.leaveGroup("groupID", new ZIMGroupLeftCallback() {
    @Override
    public void onGroupLeft(ZIMError errorInfo) {
        // 通过 errorInfo.code 获取主动退出群组的结果     
    }
});

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

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

// 群主移除群内成员
ArrayList<String> user_list = new ArrayList<>();
user_list.add("user_1");
user_list.add("user_2");
zim.kickGroupMembers(user_list, "groupID", new ZIMGroupMemberKickedCallback() {
    @Override
    public void onGroupMemberKicked(ArrayList<String> kickedUserIDList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        // 通过 errorInfo.code 获取移除群成员的结果     
    }
});

解散群组

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

// 群主解散群组
zim.dismissGroup("groupID", new ZIMGroupDismissedCallback() {
    @Override
    public void onGroupDismissed(ZIMError errorInfo) {
        // 通过 errorInfo.code 获取群主解散群组的结果
    }
});

更多功能

查询已加入群组列表

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

// 用户查询自己加入了哪些群组
zim.queryGroupList(new ZIMGroupListQueriedCallback() {
    @Override
    public void onGroupListQueried(ArrayList<ZIMGroupInfo> groupList, ZIMError errorInfo) {
        // 通过 errorInfo.code 获取用户加入的群组结果
    }
});

搜索已加入群组

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

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

// 搜索名称中包含 “zego” 的已加入群组
ZIM zim = getZIM();
ZIMGroupMemberSearchConfig config = new ZIMGroupMemberSearchConfig();
config.count = 10;
config.nextFlag = 0;
config.isAlsoMatchGroupMemberNickname = true; // 如果群成员昵称包含 “zego”，搜索结果将包含该群组
config.isAlsoMatchGroupMemberUserName = true; // 如果群成员用户名称包含 ”zego“，搜索结果将包含该群组
config.keywords.add("zego");
zim.searchLocalGroups(config, new ZIMGroupsSearchedCallback() {
    @Override
    public void onGroupsSearched(ArrayList<ZIMGroupSearchInfo> groupSearchInfoList, int nextFlag, ZIMError errorInfo) {
          // 开发者可从 groupSearchInfoList 中获取到群组信息              
    }
});

禁言或解禁群组

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

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

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

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

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

// 设置群组禁言配置
ZIMGroupMuteConfig config = new ZIMGroupMuteConfig();
// 群组禁言模式为指定角色的群成员不能发言
config.mode = ZIMGroupMuteMode.Custom;
// 禁言时长为 30 秒
config.duration = 30;
// 角色为 3 和 5 的群成员被禁言
config.roles.add(3);
config.roles.add(5);

// 开启禁言
boolean isMute = true;

zim.muteGroup(isMute, "group_id", config, new ZIMGroupMutedCallback() {
     @Override
     public void onGroupMuted(String groupID, boolean isMute, ZIMGroupMuteInfo info, ZIMError errorInfo) {

     }
});

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

zim.setEventHandler(new ZIMEventHandler(){

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

确认群组会话是否可用

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

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

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

isDisabled 值说明如下：

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

更新入群验证模式

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

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

// 监听 onGroupVerifyInfoUpdated 事件
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // 验证模式更新回调通知
     }

   });

// 更新 他人入群验证模式
zim.updateGroupJoinMode(ZIMGroupJoinMode.AUTH, "groupID", new ZIMGroupJoinModeUpdatedCallback(){
    public void onGroupJoinModeUpdated(String groupID, ZIMGroupJoinMode mode, ZIMError errorInfo){
        // 更新验证模式结果回调通知
    }
});

更新邀请模式

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

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

// 监听 onGroupVerifyInfoUpdated 事件
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // 邀请模式更新回调通知
     }

   });

// 更新 邀请他人入群验证模式
zim.updateGroupInviteMode(ZIMGroupInviteMode.ADMIN, "groupID", new ZIMGroupInviteModeUpdatedCallback(){
    public void onGroupInviteModeUpdated(String groupID, ZIMGroupInviteMode mode, ZIMError errorInfo){
        // 更新邀请他人入群验证模式结果回调通知
    }
});

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

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

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

// 监听 onGroupVerifyInfoUpdated 事件
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // 目标用户验证模式更新回调通知

     }

   });


// 更新邀请目标用户验证模式
zim.updateGroupBeInviteMode(ZIMGroupBeInviteMode.AUTH, "groupID", new ZIMGroupBeInviteModeUpdatedCallback(){
    public void onGroupBeInviteModeUpdated(String groupID, ZIMGroupBeInviteMode mode, ZIMError errorInfo) {
            // 更新邀请目标用户验证模式回调通知
    }  
});

查询入群申请列表

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

ZIMGroupApplicationListQueryConfig config = new ZIMGroupApplicationListQueryConfig();
config.count = 10;
// 首次查询填 0
conifg.nextFlag = 0; 
zim.queryGroupApplicationList(config,  new ZIMGroupApplicationListQueriedCallback() {
     public void onGroupApplicationListQueried(ArrayList<ZIMGroupApplicationInfo> applicationList, int nextFlag, ZIMError errorInfo) {
            // 查询群申请列表结果回调
     }
})