群组管理

---

功能简介

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 字节的字符串，无特殊字符限制。
zim::ZIMGroupInfo group_info;
group_info.groupID = "group_id";
group_info.groupName = "groupName";
group_info.groupAvatarUrl = "groupAvatarUrl";

zim::ZIMGroupAdvancedConfig config;

config.groupAttributes.emplace("key_0", "value_0");
config.groupAttributes.emplace("key_1", "value_1");
config.groupAttributes.emplace("key_2", "value_2");

/**
 * 入群验证模式，仅支持 2.15.0 及以上版本的 ZIM SDK
 * ZIM_GROUP_JOIN_MODE_ANY：0，默认值，任何人可直接加群。
 * ZIM_GROUP_JOIN_MODE_AUTH：1，需要群主或管理员审批才能入群。
 * ZIM_GROUP_JOIN_MODE_FORBID：2，禁止其他用户入群。
 */
config.joinMode = zim::ZIMGroupJoinMode::ZIM_GROUP_JOIN_MODE_AUTH;
/**
 * 邀请模式，仅支持 2.15.0 及以上版本的 ZIM SDK
 * ZIM_GROUP_INVITE_MODE_ANY：0，默认值，任何群成员都可以邀请外部成员入群。
 * ZIM_GROUP_INVITE_MODE_ADMIN：1，仅限群主或管理员可以邀请外部成员入群
 */
config.inviteMode = zim::ZIMGroupInviteMode::ZIM_GROUP_INVITE_MODE_ADMIN;
/**
 * 邀请目标用户验证模式，仅支持 2.15.0 及以上版本的 ZIM SDK
 * ZIM_GROUP_BEINVITE_MODE_NONE：0，默认值，无需被邀请人同意，该用户自动成为群成员。
 * ZIM_GROUP_BEINVITE_MODE_AUTH：1，被邀请人同意后成为群成员。
 */
config.beInviteMode = zim::ZIMGroupBeInviteMode::ZIM_GROUP_BE_INVITE_MODE_AUTH;
/**
 * 群组人数上限，仅支持 2.15.0 及以上版本的 ZIM SDK
 * 取值范围: [0, 套餐默认的最大群成员数量]。
 */ 
config.maxMemberCount = 100;


std::vector<std::string> user_list;
user_list.push_back("user_1");
user_list.push_back("user_2");

zim_->createGroup(group_info, user_list, config, 
    [=](const zim::ZIMGroupFullInfo &groupInfo,
        const std::vector<zim::ZIMGroupMemberInfo> &userList,
        const std::vector<zim::ZIMErrorUser> &errorUserList,
        zim::ZIMError errorInfo {

        int error_code = errorInfo.code;

    });

加入群组

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

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

void onGroupMemberStateChanged(zim::ZIM *zim, zim::ZIMGroupMemberState state,
                                        zim::ZIMGroupMemberEvent event,
                                        const std::vector<zim::ZIMGroupMemberInfo> &userList,
                                        const zim::ZIMGroupOperatedInfo &operatedInfo,
                                        const std::string &groupID) override {
    ......
}

void onGroupStateChanged(zim::ZIM *zim, zim::ZIMGroupState state,
                                    zim::ZIMGroupEvent event,
                                    const zim::ZIMGroupOperatedInfo &operatedInfo,
                                    const zim::ZIMGroupFullInfo &groupInfo) override {
    ......
}

方式 1：主动加入群组

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

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

  // 其他客户端直接加入群组
  zim_->joinGroup(group_id,
                  [=](const zim::ZIMGroupFullInfo &groupInfo, zim::ZIMError errorInfo) {
          int error_code = errorInfo.code;
      });

• 当 joinMode 为 1（ZIM_GROUP_JOIN_MODE_AUTH）时：

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

     zim::ZIMGroupJoinApplicationSendConfig config;
     config.wording = "wording";
     
     zim_->sendGroupJoinApplication(
         group_id, config,
         [=](const std::string &groupID, const zim::ZIMError &errorInfo) {
             int error_code = errorInfo.code;
         });

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

     void onGroupApplicationListChanged(
         zim::ZIM * /*zim*/, const std::vector<zim::ZIMGroupApplicationInfo> & /*applicationList*/,
         zim::ZIMGroupApplicationListChangeAction /*action*/) override {
             ......
     }

  3. 群主或管理员审批

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

       // 同意申请
       zim::ZIMGroupJoinApplicationAcceptConfig config;
       
       zim_->acceptGroupJoinApplication(
           user_id, group_id, config,
           [=](const std::string &groupID, const std::string &userID,
               const zim::ZIMError &errorInfo) {
               int error_code = errorInfo.code;
           });

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

       // 否决申请
       zim::ZIMGroupJoinApplicationRejectConfig config;
       
       zim_->rejectGroupJoinApplication(
           user_id, group_id, config,
           [=](const std::string &groupID, const std::string &userID, const zim::ZIMError &errorInfo) {
               int error_code = errorInfo.code;
           });

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

     void onGroupApplicationUpdated(
         zim::ZIM * /*zim*/,
         const std::vector<zim::ZIMGroupApplicationInfo> & /*applicationList*/) override {
         ......
     }

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

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

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

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

     // 由群内成员添加入群组
     std::vector<std::string> user_list;
     user_list.push_back("user_1");
     user_list.push_back("user_2");
     zim_->inviteUsersIntoGroup(user_list, group_id, callback);

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

     // 发送邀请入群申请
     std::vector<std::string> user_list;
     user_list.push_back("user_1");
     user_list.push_back("user_2");
     
     zim::ZIMGroupInviteApplicationSendConfig config;
     config.wording = "wording";
     
     zim_->sendGroupInviteApplications(
         user_list, group_id, config,
         [=](const std::string &groupID, const std::vector<zim::ZIMErrorUserInfo> &errorUserList,
             const zim::ZIMError &errorInfo) {
             int error_code = errorInfo.code;
         });

     根据群组的 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（ZIM_GROUP_BEINVITE_MODE_AUTH）时，目标用户和邀请人（仅当接口调用人为群主和群管理员时）会通过 onGroupApplicationListChanged 收到回调通知。目标用户需要审批该申请。

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

     同意邀请入群申请
     zim::ZIMGroupInviteApplicationAcceptConfig config;
     
     zim_->acceptGroupInviteApplication(
         user_id, group_id, config,
         [=](const zim::ZIMGroupFullInfo &group, const std::string &inviterUserID,
             const zim::ZIMError &errorInfo) {
             int error_code = errorInfo.code;
         });

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

     拒绝邀请入群申请
     zim::ZIMGroupInviteApplicationRejectConfig config;
     
     zim_->rejectGroupInviteApplication(
          user_id, group_id, config,
         [=](const std::string &groupID, const std::string &inviterUserID,
             const zim::ZIMError &errorInfo) {
             int error_code = errorInfo.code;
         });

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

   // 监听 onGroupApplicationUpdated
   void onGroupApplicationUpdated(
       zim::ZIM * /*zim*/,
       const std::vector<zim::ZIMGroupApplicationInfo> & /*applicationList*/) override {
       ......
   }

退出群组

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

方式 1：主动退出群组

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

// 主动退出群组
zim_->leaveGroup(group_id, [=](const std::string &groupID, zim::ZIMError errorInfo){

    int error_code = errorInfo.code;

});

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

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

// 群主移除群内成员
std::vector<std::string> user_list;
user_list.push_back("user_1");
user_list.push_back("user_2");
zim_->kickGroupMembers(user_list, group_id, 
    [=](const std::string &groupID, const std::vector<std::string> &kickedMemberIDs,
    const std::vector<ZIMErrorUser> &errorUserList, zim::ZIMError errorInfo) {

        int error_code = errorInfo.code;

    });

解散群组

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

// 群主解散群组
zim_->dismissGroup(group_id, [=](const std::string &groupID, zim::ZIMError errorInfo) {
    int error_code = errorInfo.code;
});

更多功能

查询已加入群组列表

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

// 用户查询自己加入了哪些群组
zim_->queryGroupList(
    [=](const std::vector<ZIMGroupInfo> &groupList, zim::ZIMError errorInfo){
        int error_code = errorInfo.code;
    });

搜索已加入群组

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

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

// 搜索名称中包含 “zego” 的已加入群组

auto searchConfig = zim::ZIMGroupSearchConfig();
searchConfig.count = 10;
searchConfig.nextFlag = 0;
// 如果群成员昵称包含 “zego” ，搜索结果将包含该群组
searchConfig.isAlsoMatchGroupMemberNickname = true;
// 如果群成员用户名称包含 “zego” ，搜索结果将包含该群组
searchConfig.isAlsoMatchGroupMemberUserName = true;
searchConfig.keywords.emplace_back("zego");

zim_->searchLocalGroups(searchConfig,
                        [=](const std::vector<zim::ZIMGroupSearchInfo> &groupSearchInfoList,
                            unsigned int nextFlag, const zim::ZIMError &errorInfo) {
                            // 开发者可从 groupSearchInfoList 中获取到群组信息
                        });

禁言或解禁群组

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

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

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

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

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

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

// 开启禁言
bool is_mute = true;

zim_->muteGroup(is_mute, group_id, config,
                    [=](const std::string &groupID, bool is_muted,
                        const zim::ZIMGroupMuteInfo &info,
                        const zim::ZIMError &errorInfo) {
                            // 开发者可从 info 中获取到群组禁言信息
                        });

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

void zim_event_handler::onGroupMutedInfoUpdated(zim::ZIM *, const zim::ZIMGroupMuteInfo &info,
                                               const zim::ZIMGroupOperatedInfo &operatedInfo,
                                               const std::string &groupID) {
    // 通过继承 ZIMEventHandler 的方式，在这里监听群禁言状态变更的信息，并进行相应处理
}

确认群组会话是否可用

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

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

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

isDisabled 值说明如下：

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

更新入群验证模式

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

// 更新 邀请他人入群验证模式
zim_->updateGroupJoinMode(
    zim::ZIMGroupJoinMode::ZIM_GROUP_JOIN_MODE_AUTH, group_id,
    [=](const std::string &groupID, zim::ZIMGroupJoinMode mode,
        const zim::ZIMError &errorInfo) {
        // 业务代码
    });

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

// 监听 onGroupVerifyInfoUpdated 事件
void onGroupVerifyInfoUpdated(zim::ZIM * /*zim*/,
                                const zim::ZIMGroupVerifyInfo & /*verifyInfo*/,
                                const zim::ZIMGroupOperatedInfo & /*operatedInfo*/,
                                const std::string & /*groupID*/) override {
    ......
}

更新邀请模式

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

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

// 监听 onGroupVerifyInfoUpdated 事件
void onGroupVerifyInfoUpdated(zim::ZIM * /*zim*/,
                                const zim::ZIMGroupVerifyInfo & /*verifyInfo*/,
                                const zim::ZIMGroupOperatedInfo & /*operatedInfo*/,
                                const std::string & /*groupID*/) override {
    ......
}

// 更新邀请模式
zim_->updateGroupInviteMode(
    zim::ZIMGroupInviteMode::ZIM_GROUP_INVITE_MODE_ADMIN, group_id,
    [=](const std::string &groupID, zim::ZIMGroupInviteMode mode,
        const zim::ZIMError &errorInfo) {
        // 业务代码
    });

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

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

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

// 监听 onGroupVerifyInfoUpdated 事件
void onGroupVerifyInfoUpdated(zim::ZIM * /*zim*/,
                                const zim::ZIMGroupVerifyInfo & /*verifyInfo*/,
                                const zim::ZIMGroupOperatedInfo & /*operatedInfo*/,
                                const std::string & /*groupID*/) override {
    ......
}

// 更新目标用户验证模式
zim_->updateGroupBeInviteMode(
    zim::ZIMGroupBeInviteMode::ZIM_GROUP_BE_INVITE_MODE_AUTH, group_id,
    [=](const std::string &groupID, zim::ZIMGroupBeInviteMode mode,
        const zim::ZIMError &errorInfo) {
        // 业务代码
    });

查询入群申请列表

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

zim::ZIMGroupApplicationListQueryConfig config;
config.count = 100;
config.nextFlag = 0;

zim_->queryGroupApplicationList(
    config, [=](const std::vector<zim::ZIMGroupApplicationInfo> &applicationList,
                unsigned long long nextFlag, const zim::ZIMError &errorInfo) {
        // 业务代码
    });