tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    Web

    最后更新时间：2023-03-23 15:42:23
    下载PDF

      功能描述

      群成员管理指的是对成员进行列表拉取、禁言、踢人、授权、转让群主等操作。

      获取群成员列表

      注意：

      • 从 v2.6.2 起，该接口支持拉取群成员禁言截止时间戳（muteUntil），接入侧可根据此值判断群成员是否被禁言，以及禁言的剩余时间。在低于v2.6.2的版本，该接口获取的群成员列表中的资料是不完整的（仅包括头像、昵称等，能够满足群成员列表的渲染需求），若要查询群成员禁言截止时间戳（muteUntil）等详细资料，请使用 getGroupMemberProfile。
      • 该接口是分页拉取群成员，不能直接用于获取群的总人数。获取群的总人数（memberCount）请使用 getGroupProfile。
      • 从 v2.22.0 起，对直播群（AVChatRoom）增加以下特殊限制：
        • 旗舰版支持拉取最近入群群成员最多 1000 人，新进来的成员排在前面。需要您购买旗舰版套餐且前往 控制台 开启开关。
        • 旗舰版使用该接口时 SDK 会忽略 count 参数，单次查询默认最多返回 500 个群成员。
        • 旗舰版接口调用默认限制 3 秒 1 次请求，如果需要定时查询群成员列表，建议每 10 秒请求一次。
        • 群成员资料信息仅支持 userID | nick | avatar | joinTime 字段，设置 nick 和 avatar 信息请调用：updateMyProfile。

      旗舰版如需户开启直播群在线成员列表功能，请登录 即时通信 IM 控制台 修改相关配置，配置页面如下图所示：

      接口

      tim.getGroupMemberList(options);

      参数

      参数 options 为 Object 类型，包含的属性值如下：

      Name Type Description
      groupID String 群组 ID
      count Number 需要拉取的数量。默认值：15，最大值：100，避免回包过大导致请求失败。若传入超过100，则只拉取前100个
      offset Number 偏移量，默认从0开始拉取

      返回值

      Promise 对象。

      示例

      let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // 从0开始拉取30个群成员
      promise.then(function(imResponse) {
        console.log(imResponse.data.memberList); // 群成员列表
      }).catch(function(imError) {
        console.warn('getGroupMemberList error:', imError);
      });
      // 从 v2.6.2 起，该接口支持拉取群成员禁言截止时间戳。
      let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // 从0开始拉取30个群成员
      promise.then(function(imResponse) {
        console.log(imResponse.data.memberList); // 群成员列表
        for (let groupMember of imResponse.data.memberList) {
          if (groupMember.muteUntil * 1000  > Date.now()) {
            console.log(`${groupMember.userID} 禁言中`);
          } else {
            console.log(`${groupMember.userID} 未被禁言`);
          }
        }
      }).catch(function(imError) {
          console.warn('getGroupMemberProfile error:', imError);
      });
      // 从 v2.22.0 起，旗舰版套餐支持获取直播群在线成员列表
      let promise = tim.getGroupMemberList({ groupID: 'group1', offset:0 }); // 默认从0开始拉取
      promise.then(function(imResponse) {
        console.log(imResponse.data.memberList); // 群成员列表
      }).catch(function(imError) {
        console.warn('getGroupMemberList error:', imError);
      });

      禁言

      禁言指定群成员

      注意：

      • 只有群主和管理员拥有该操作权限：群主可以禁言/取消禁言管理员和普通群成员。管理员可以禁言/取消禁言普通群成员。
      • v2.19.1 起，支持设置社群成员在话题中的禁言时间，groupID 传入 topicID 即可。

      接口

      tim.setGroupMemberMuteTime(options);

      参数

      参数 options 为 Object 类型，包含的属性值如下：

      Name Type Description
      groupID String 群组 ID 或 话题 ID
      userID String 用户 ID
      muteTime Number 禁言时长，单位秒。如设为1000，则表示从现在起禁言该用户1000秒；设为0，则表示取消禁言。

      返回值

      Promise 对象。

      示例

      let promise = tim.setGroupMemberMuteTime({
        groupID: 'group1',
        userID: 'user1',
        muteTime: 600 // 禁言10分钟；设为0，则表示取消禁言
      });
      promise.then(function(imResponse) {
        console.log(imResponse.data.group); // 修改后的群资料
        console.log(imResponse.data.member); // 修改后的群成员资料
      }).catch(function(imError) {
        console.warn('setGroupMemberMuteTime error:', imError); // 禁言失败的相关信息
      });
      // 设置群成员在话题中的禁言时间
      let promise = tim.setGroupMemberMuteTime({
        groupID: 'topicID',
        userID: 'user1',
        muteTime: 600 // 禁言10分钟；设为0，则表示取消禁言
      });
      promise.then(function(imResponse) {
        console.log(imResponse.data.group); // 修改后的群资料
        console.log(imResponse.data.member); // 修改后的群成员资料
      }).catch(function(imError) {
        console.warn('setGroupMemberMuteTime error:', imError); // 禁言失败的相关信息
      });

      禁言整个群

      // v2.6.2 起，提供了全体禁言和取消禁言的功能。目前群全体禁言后，不支持下发群提示消息。
      let promise = tim.updateGroupProfile({
        groupID: 'group1',
        muteAllMembers: true, // true 表示全体禁言，false表示取消全体禁言
      });
      promise.then(function(imResponse) {
        console.log(imResponse.data.group) // 修改成功后的群组详细资料
      }).catch(function(imError) {
        console.warn('updateGroupProfile error:', imError); // 修改群组资料失败的相关信息
      });

      踢人

      注意：

      • 从 v2.22.0 起，旗舰版支持直播群（AVChatRoom）踢人。
      • 踢出时长字段（duration）仅直播群（AVChatRoom）支持，单位：秒。
      • 成员被踢出直播群后，App 管理员可以通过 RESTAPI 解封群成员，解封之后该成员可以再次加群。

      接口

      tim.deleteGroupMember(options);

      参数

      参数 options 为 Object 类型，包含的属性值如下：

      Name Type Description
      groupID String 群组 ID 或 话题 ID
      userIDList Array 待删除的群成员的 ID 列表
      reason String | undefined 踢人的原因
      duration Number 踢出时长，必须大于 0（仅直播群支持）

      返回值

      Promise 对象。

      示例

      // 非直播群踢出群成员
      let promise = tim.deleteGroupMember({groupID: 'group1', userIDList:['user1'], reason: '你违规了，我要踢你！'});
      promise.then(function(imResponse) {
        console.log(imResponse.data.group); // 删除后的群组信息
        console.log(imResponse.data.userIDList); // 被删除的群成员的 userID 列表
      }).catch(function(imError) {
        console.warn('deleteGroupMember error:', imError); // 错误信息
      });
      // 从v2.22.0 起，支持直播群踢出群成员
      let promise = tim.deleteGroupMember({groupID: 'group1', userIDList:['user1'], reason: '你违规了，我要踢你！', duration: 60});
      promise.then(function(imResponse) {
        console.log(imResponse.data.group); // 删除后的群组信息
        console.log(imResponse.data.userIDList); // 被删除的群成员的 userID 列表
      }).catch(function(imError) {
        console.warn('deleteGroupMember error:', imError); // 错误信息
      });

      修改群成员角色

      接口

      tim.setGroupMemberRole(options);

      参数

      参数 options 为 Object 类型，包含的属性值如下：

      Name Type Description
      groupID String 群组 ID 或 话题 ID
      userID String 用户 ID
      role String 可选值：TIM.TYPES.GRP_MBR_ROLE_ADMIN（群管理员）,TIM.TYPES.GRP_MBR_ROLE_MEMBER（群普通成员）,TIM.TYPES.GRP_MBR_ROLE_CUSTOM（自定义群成员角色，仅社群支持）

      返回值

      Promise 对象。

      示例

      let promise = tim.setGroupMemberRole({
        groupID: 'group1',
        userID: 'user1',
        role: TIM.TYPES.GRP_MBR_ROLE_ADMIN // 将群 ID: group1 中的用户：user1 设为管理员
      });
      promise.then(function(imResponse) {
        console.log(imResponse.data.group); // 修改后的群资料
        console.log(imResponse.data.member); // 修改后的群成员资料
      }).catch(function(imError) {
        console.warn('setGroupMemberRole error:', imError); // 错误信息
      });

      获取群在线人数

      注意：

      • 目前该接口仅支持直播群（AVChatRoom）。
      • 当不在直播群内或非直播群使用此API查询人数时，SDK 返回的 memberCount 为0。调用此接口查询直播群人数的频率建议控制在5~10秒一次。

      接口

      tim.getGroupOnlineMemberCount(groupID);

      参数

      Name Type Description
      groupID String 群组 ID

      返回值

      Promise 对象。

      示例

      // v2.8.0 起，支持查询直播群在线人数
      let promise = tim.getGroupOnlineMemberCount('group1');
      promise.then(function(imResponse) {
        console.log(imResponse.data.memberCount);
      }).catch(function(imError) {
        console.warn('getGroupOnlineMemberCount error:', imError); // 获取直播群在线人数失败的相关信息
      });
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2023 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款