即时通信 IM
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 即时通信 IM > 无 UI 集成 > 群组相关 > 群成员管理 > Web&小程序&uni-app

Web&小程序&uni-app

最近更新时间：2023-08-22 09:46:21

我的收藏

本页目录：

功能描述

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

获取群成员列表

注意
1. 该接口支持拉取群成员禁言截止时间戳（muteUntil），接入侧可根据此值判断群成员是否被禁言，以及禁言的剩余时间。
2. 该接口是分页拉取群成员，不能直接用于获取群的总人数。获取群的总人数（memberCount）请使用 getGroupProfile。
3. 当接口返回的 offset 为 0 时说明群成员已经拉取完成。
4. 对直播群（AVChatRoom）增加以下特殊限制：
旗舰版支持拉取最近入群群成员最多 1000 人，新进来的成员排在前面。需要您购买旗舰版套餐且前往 控制台 开启开关。
旗舰版使用该接口时 SDK 会忽略 count 参数，单次查询默认最多返回 500 个群成员。
旗舰版接口调用默认限制 3 秒 1 次请求，如果需要定时查询群成员列表，建议每 10 秒请求一次。
群成员资料信息仅支持 userID | nick | avatar | joinTime 字段，设置 nick 和 avatar 信息请调用：updateMyProfile。
5. 旗舰版支持直播群（AVChatRoom）根据 filter 参数拉取指定标记的群成员列表。标记群成员请参考：markGroupMemberList。
旗舰版套餐包如需开启直播群在线成员列表功能，请登录 即时通信 IM 控制台 修改相关配置，配置页面如下图所示：

接口
chat.getGroupMemberList(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
groupID
String
群组 ID
role
String
群成员角色。默认 SDK 拉取所有的群成员，您可以通过设置此字段拉取指定角色的群成员列表（v3.1.3起支持），支持的值如下：
TencentCloudChat.GRP_MBR_ROLE_OWNER - 群主
TencentCloudChat.GRP_MBR_ROLE_ADMIN - 群管理员
TencentCloudChat.GRP_MBR_ROLE_MEMBER - 普通群成员
count
Number
需要拉取的数量。默认值：15，最大值：100，避免回包过大导致请求失败。若传入超过 100，则只拉取前 100 个（旗舰版套餐直播群使用该接口时忽略 count 参数）。
offset
Number
偏移量，默认从0开始拉取。
返回值
Promise
示例
let promise = chat.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);
});
// 该接口支持拉取群成员禁言截止时间戳。
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);
});
// 旗舰版套餐支持获取直播群在线成员列表
let promise = chat.getGroupMemberList({
   groupID: 'group1',
   offset:0， // 默认从 0 开始拉取
 });
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // 群成员列表
}).catch(function(imError) {
  console.warn('getGroupMemberList error:', imError);
});

禁言

禁言指定群成员

注意
1. TencentCloudChat.TYPES.GRP_WORK 类型的群组（即好友工作群）不支持此操作。
2. TencentCloudChat.TYPES.GRP_AVCHATROOM 类型的群组（即直播群）不支持此操作。
3. 直播群【封禁】或者【踢出】群成员，需要您购买旗舰版套餐，并调用 deleteGroupMember 接口实现。
4. 如果需要【全体禁言】，请参考 updateGroupProfile。
5. 支持设置社群成员在话题中的禁言时间，groupID 传入 topicID 即可。
6. 只有群主和管理员拥有该操作权限：
群主可以禁言/取消禁言管理员和普通群成员。
管理员可以禁言/取消禁言普通群成员。
接口
chat.setGroupMemberMuteTime(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
groupID
String
群组 ID 或 话题 ID
userID
String
用户 ID
muteTime
Number
禁言时长，单位秒。如设为1000，则表示从现在起禁言该用户 1000 秒；设为0，则表示取消禁言。
返回值
Promise
示例
let promise = chat.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 = chat.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); // 禁言失败的相关信息
});

禁言整个群

// 全体禁言
let promise = chat.updateGroupProfile({
  groupID: 'group1',
  muteAllMembers: true, // true 表示全体禁言，false表示取消全体禁言
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group) // 修改成功后的群组详细资料
}).catch(function(imError) {
  console.warn('updateGroupProfile error:', imError); // 修改群组资料失败的相关信息
});

踢人

注意
1. 旗舰版套餐包支持删除直播群群成员。您可以通过调用此接口实现直播群【封禁群成员】的效果。
2. 踢出时长字段仅直播群（AVChatRoom）支持。
3. 群成员被移除出直播群后，在踢出时长内如果用户想再次进群，需要 App 管理员调用 RESTAPI 解封。过了踢出时长，用户可再次主动加入直播群。
接口
chat.deleteGroupMember(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
groupID
String
群组 ID 或 话题 ID
userIDList
Array
待删除的群成员的 ID 列表
reason
String | undefined
踢人的原因
duration
Number
踢出时长，必须大于 0（仅直播群支持）
返回值
Promise
示例
// 非直播群踢出群成员
let promise = chat.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); // 错误信息
});
// 直播群踢出群成员
let promise = chat.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); // 错误信息
});

修改群成员角色

注意
1. TencentCloudChat.TYPES.GRP_WORK 类型的群组（即好友工作群）不支持此操作。
2. TencentCloudChat.TYPES.GRP_AVCHATROOM类型的群组（即直播群）不支持此操作。
接口
chat.setGroupMemberRole(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
groupID
String
群组 ID 或 话题 ID
userID
String
用户 ID
role
String
可选值：
TencentCloudChat.TYPES.GRP_MBR_ROLE_ADMIN（群管理员）,
TencentCloudChat.TYPES.GRP_MBR_ROLE_MEMBER（群普通成员）,
TencentCloudChat.TYPES.GRP_MBR_ROLE_CUSTOM（自定义群成员角色，仅社群支持）
返回值
Promise
示例
let promise = chat.setGroupMemberRole({
  groupID: 'group1',
  userID: 'user1',
  role: TencentCloudChat.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); // 错误信息
});

获取群在线人数

注意
1. 目前该接口仅支持直播群（AVChatRoom）。
2. 当不在直播群内或非直播群使用此API查询人数时，SDK 返回的 memberCount 为0。调用此接口查询直播群人数的频率建议控制在 5~10 秒一次。
接口
chat.getGroupOnlineMemberCount(groupID);
参数
Name
Type
Description
groupID
String
群组 ID
返回值
Promise
示例
// 查询直播群在线人数
let promise = chat.getGroupOnlineMemberCount('group1');
promise.then(function(imResponse) {
  console.log(imResponse.data.memberCount);
}).catch(function(imError) {
  console.warn('getGroupOnlineMemberCount error:', imError); // 获取直播群在线人数失败的相关信息
});

中国站