群组管理

---

功能简介

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

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

前提条件

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

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

创建群组

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

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

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


// 设置入群模式和群组人数上限
var config1 = {
    /**
     * 入群验证模式，仅支持 2.15.0 及以上版本的 ZIM SDK
     * 0：（默认）任何人可直接加群。
     * 1：需要群主或管理员审批才能入群。
     * 2：禁止其他用户入群。
     */
    joinMode: 1, 
    /**
     * 邀请模式，仅支持 2.15.0 及以上版本的 ZIM SDK
     * 0：（默认）任何群成员都可以邀请外部成员入群。
     * 1：仅限群主或管理员可以邀请外部成员入群。
     */
    inviteMode: 1,
    /**
     * 邀请目标用户验证模式，仅支持 2.15.0 及以上版本的 ZIM SDK
     * 0：（默认）无需被邀请人同意，该用户自动成为群成员。
     * 1：被邀请人同意后成为群成员。
     */
    beInviteMode: 1,
    /**
     * 群组人数上限，仅支持 2.15.0 及以上版本的 ZIM SDK
     * 取值范围: [0, 套餐默认的最大群成员数量]。
     */    
    maxMemberCount: 100 // 限制群成员总人数 100
};
zim.createGroup(groupInfo, userIDs, config1)
    .then(function ({ groupInfo, userList, errorUserList }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

加入群组

其他用户登录 ZIM SDK 后，可以通过主动加入或被邀请加入由 A 创建的群组。如果用户加入成功后，全体群成员（包括该新成员）都会收到 groupMemberStateChanged 和 groupStateChanged 的回调通知：

// 注册监听“群成员状态变更”的回调
zim.on('groupMemberStateChanged', function (zim, { groupID, state, event, userList, operatedInfo }) {
    console.log('groupMemberStateChanged', groupID, state, event, userList, operatedInfo);
});

// 注册监听“群状态变更”的回调
zim.on('groupStateChanged', function (zim, { state, event, groupInfo, operatedInfo }) {
    console.log('groupStateChanged', state, event, groupInfo, operatedInfo);
});

方式 1：主动加入群组

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

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

  var groupID = '';
  
  // 其他客户端直接加入群组
  zim.joinGroup(groupID)
      .then(function ({ groupInfo }) {
          // 操作成功
      })
      .catch(function (err) {
          // 操作失败
      });

• 当 joinMode 为 1 时：

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

     // 申请加入群组
     var groupID = '';
     var config = {
         wording: 'XXXX 申请加入群组' // 申请附言
     };
     zim.sendGroupJoinApplication(groupID, config)
         .then(function ({ groupID }) {
             // 操作成功
         })
         .catch(function (err) {
             // 操作失败
         });

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

     // 监听 groupApplicationListChanged 事件
     zim.on('groupApplicationListChanged', (zim, { action, applicationList }) => {
         // 新增了入群申请，此时可更新入群申请列表 UI
         console.log(action, applicationList);
     });

  3. 群主或管理员审批

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

       var userID = '';
       var groupID = '';
       var config = {};
       zim.acceptGroupJoinApplication(userID, groupID, config)
           .then(function ({ groupID, userID }) {
               // 操作成功
           })
           .catch(function (err) {
               // 操作失败
           });

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

       var userID = '';
       var groupID = '';
       var config = {};
       zim.rejectGroupJoinApplication(userID, groupID, config)
           .then(function ({ groupID, userID }) {
               // 操作成功
           })
           .catch(function (err) {
               // 操作失败
           });

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

     // 监听 groupApplicationUpdated 事件
     zim.on('groupApplicationUpdated', (zim, { applicationList }) => {
         // 入群申请有变更，此时可更新入群申请列表 UI
         console.log(applicationList);
     });

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

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

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

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

     var groupID = '';
     
     // 由群内成员添加入群组
     var userIDs = [];
     zim.inviteUsersIntoGroup(userIDs, groupID)
         .then(function ({ groupID, userList, errorUserList }) {
             // 操作成功
         })
         .catch(function (err) {
             // 操作失败
         });

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

     // 发送邀请入群申请
     var userIDs = [];
     var groupID = '';
     var config = {
         wording: '邀请加入群组' // 申请附言
     };
     zim.sendGroupInviteApplications(userIDs, groupID, config)
         .then(function ({ groupID, errorUserList }) {
             // 操作成功，邀请失败的用户通过 errorUserList 获取 
         })
         .catch(function (err) {
             // 操作失败
         });

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

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

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

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

     var inviterUserID = '';
     var groupID = '';
     
     // 同意邀请入群申请
     var config = {};
     zim.acceptGroupInviteApplication(inviterUserID, groupID, config)
         .then(function ({ groupInfo, inviterUserID }) {
             // 操作成功
         })
         .catch(function (err) {
             // 操作失败
         }); 

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

     var inviterUserID = '';
     var groupID = '';
     
     // 拒绝邀请入群申请
     var config = {};
     zim.rejectGroupInviteApplication(inviterUserID, groupID, config)
         .then(function ({ groupID, inviterUserID }) {
             // 操作成功
         })
         .catch(function (err) {
             // 操作失败
         });

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

   // 监听 groupApplicationUpdated 事件
   zim.on('groupApplicationUpdated', (zim, { applicationList }) => {
       // 入群申请有变更，此时可更新入群申请列表 UI
       console.log(applicationList);
   });

退出群组

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

方式 1：主动退出群组

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

var groupID = '';

// 主动退出群组
zim.leaveGroup(groupID)
    .then(function ({ groupID }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

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

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

var groupID = '';

// 群主或管理员移除群内成员
var userIDs = [];
zim.kickGroupMembers(userIDs, groupID)
    .then(function ({ groupID, kickedUserIDs, errorUserList }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

解散群组

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

var groupID = '';
zim.dismissGroup(groupID)
    .then(function ({ groupID }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 注册监听“群状态变更”的回调
zim.on('groupStateChanged', function (zim, { state, event, groupInfo, operatedInfo }) {
    console.log('groupStateChanged', state, event, groupInfo, operatedInfo);
});

进阶功能

查询已加入群组列表

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

zim.queryGroupList()
    .then(function ({ groupList }) {
        // 查询成功
    })
    .catch(function (err) {
        // 查询失败
    });

搜索已加入群组

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

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

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

var config = {
    count: 10, // 搜索结果数量
    nextFlag: 0,
    keywords: ['zego'], // 设置关键词为 “zego”，最多支持 5 个。当设置多个关键词后，搜索结果只展示同时包含所有关键词的本地消息
    isAlsoMatchGroupMemberUserName: true, // 如果群成员用户名称包含 “zego”，搜索结果将包含该群成员
    isAlsoMatchGroupMemberNickname: false,
};

zim.searchLocalGroups(config)
    .then(function ({ groupSearchInfoList, nextFlag }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

禁言或解禁群组

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

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

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

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

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

// 设置群组禁言配置
const config = {
    mode: 3, //群组禁言模式为指定角色的群成员不能发言
    duration: 30, //禁言时长为 30 秒
    roles:[3,5],//角色为 3 和 5 的群成员被禁言
};

// 开启禁言
var isMute = true;
var groupID = 'group';

zim.muteGroup(isMute, groupID, config)
    .then(function ({ groupID, isMute, mutedInfo }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

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

zim.on('groupMutedInfoUpdated', function (zim, { groupID, mutedInfo, operatedInfo}) {
    console.log('groupMutedInfoUpdated', groupID, mutedInfo, event, userList, operatedInfo);
});

确认群组会话是否可用

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

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

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

isDisabled 值说明如下：

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

更新入群验证模式

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

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

// 监听 groupVerifyInfoUpdated 事件
zim.on('groupVerifyInfoUpdated', (zim, { groupID, verifyInfo, operatedInfo }) => {
    console.log(groupID, verifyInfo.joinMode);
});

var groupID = '';

// 更新入群验证模式
var joinMode = 1;
zim.updateGroupJoinMode(joinMode, groupID)
    .then(function ({ groupID, mode }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

更新邀请模式

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

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

// 监听 groupVerifyInfoUpdated 事件
zim.on('groupVerifyInfoUpdated', (zim, { groupID, verifyInfo, operatedInfo }) => {
    console.log(groupID, verifyInfo.inviteMode);
});

var groupID = '';

// 更新 邀请他人入群验证模式
var inviteMode = 1;
zim.updateGroupInviteMode(inviteMode, groupID)
    .then(function ({ groupID, mode }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

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

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

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

// 监听 groupVerifyInfoUpdated 事件
zim.on('groupVerifyInfoUpdated', (zim, { groupID, verifyInfo, operatedInfo }) => {
    console.log(groupID, verifyInfo.beInviteMode);
});

var groupID = '';

// 更新邀请目标用户验证模式
var beInviteMode = 1;
zim.updateGroupBeInviteMode(beInviteMode, groupID)
    .then(function ({ groupID, mode }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

查询入群申请列表

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

// 查询入群申请列表
var config = {
    count: 30, // 单次查询数量
    nextFlag: 0 // 锚点，首次查询填 0，下次查询使用当前查询返回 nextFlag 作为锚点
};

zim.queryGroupApplicationList(config)
    .then(function ({ nextFlag, applicationList }) {
        // 操作成功，下次查询使用 nextFlag 作为锚点
    })
    .catch(function (err) {
        // 操作失败
    });