tencent cloud

文档反馈

JavaScript

最后更新时间:2024-11-15 11:37:05

    功能描述

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

    获取群成员列表

    说明:
    1. v3.2.0起,如果您购买了进阶版套餐,此接口返回的群成员资料新增 isOnline 字段,标识成员是否在线。
    2. 该接口支持拉取群成员禁言截止时间戳(muteUntil),接入侧可根据此值判断群成员是否被禁言,以及禁言的剩余时间。
    3. 该接口是分页拉取群成员,不能直接用于获取群的总人数。获取群的总人数(memberCount)请使用 getGroupProfile
    4. 当接口返回的 offset 为 0 时说明群成员已经拉取完成。
    5. 进阶版支持直播群(AVChatRoom)根据 filter 参数拉取指定标记的群成员列表。标记群成员请参考:markGroupMemberList
    6. 对直播群(AVChatRoom)增加以下特殊限制:
    进阶版支持拉取最近入群群成员最多 1000 人,新进来的成员排在前面。需要您购买进阶版套餐且前往 Chat Console 开启开关。
    进阶版使用该接口时 SDK 会忽略 count 参数,单次查询默认最多返回 500 个群成员。
    进阶版接口调用默认限制 3 秒 1 次请求,如果需要定时查询群成员列表,建议每 10 秒请求一次。
    群成员资料信息仅支持 userID | nick | avatar | joinTime | isOnline 字段,设置 nick 和 avatar 信息请调用:updateMyProfile
    进阶版如需开启直播群在线成员列表功能,请登录 Chat Console 修改相关配置,配置页面如下图所示:
    
    接口
    chat.getGroupMemberList(options);
    参数
    参数 optionsObject 类型,包含的属性值如下:
    参数
    类型
    说明
    groupID
    String
    群组 ID
    role
    String
    群成员角色。默认 SDK 拉取所有的群成员,您可以通过设置此字段拉取指定角色的群成员列表,支持的值如下:
    TencentCloudChat.GRP_MBR_ROLE_OWNER - 群主
    TencentCloudChat.GRP_MBR_ROLE_ADMIN - 群管理员
    TencentCloudChat.GRP_MBR_ROLE_MEMBER - 普通群成员
    
    count
    Number
    需要拉取的数量。默认值:15,最大值:100,避免回包过大导致请求失败。若传入超过 100,则只拉取前 100 个(进阶版套餐直播群使用该接口时忽略 count 参数)。
    offset
    Number | String
    偏移量,默认从0开始拉取。社群(Community)使用时该字段为 String 类型。
    filter
    Number
    群成员自定义标记,仅直播群(AVChatRoom)支持
    返回值
    Promise
    示例
    // 拉取此群的所有管理员
    let promise = chat.getGroupMemberList({
    groupID: 'group1',
    role: TencentCloudChat.TYPES.GRP_MBR_ROLE_ADMIN,
    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);
    });
    // 支持获取直播群指定标记的在线成员列表
    // 从 0 开始拉取,默认一次最多返回 500 个群成员 let promise = chat.getGroupMemberList({ groupID: 'group1', filter: 1000, offset: 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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    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. TencentCloudChat.TYPES.GRP_WORK(好友工作群):默认任何群成员都可以直接邀请他人进群,且无需被邀请人同意,直接将其拉入群组中。可将 inviteOption 设置为 TencentCloudChat.TYPES.INVITE_OPTIONS_DISABLE_INVITE 禁止任何群成员邀请他人进群。
    2. TencentCloudChat.TYPES.GRP_PUBLIC(陌生人社交群)/ TencentCloudChat.TYPES.GRP_MEETING(临时会议群):默认不支持群成员邀请他人进群,可通过设置 inviteOption 控制邀请进群选项。
    3. TencentCloudChat.TYPES.GRP_COMMUNITY(社群):默认支持群成员邀请他人进群。
    4. TencentCloudChat.TYPES.GRP_AVCHATROOM(直播群):不允许任何人邀请他人入群(包括 App 管理员)。
    5. 待添加的成员 userID 必须为有效的用户账号,否则接口将返回10019。
    接口
    chat.addGroupMember(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    groupID
    String
    群组 ID 或 话题 ID。
    userIDList
    Array.<String>
    待添加的 userID 列表,单次最多添加20个成员。
    返回值
    Promise
    示例
    let promise = chat.addGroupMember({groupID: 'publicTest', userIDList: ['user1','user2','user3']});
    promise.then(function(imResponse) {
    console.log(imResponse.data.successUserIDList);
    console.log(imResponse.data.failureUserIDList);
    console.log(imResponse.data.existedUserIDList);
    // 一个用户 userX 最多允许加入 N 个群,如果已经加入了 N 个群,此时再尝试添加 userX 为群成员,则 userX 不能正常加群
    // SDK 将 userX 的信息放入 overLimitUserIDList,供接入侧处理
    console.log(imResponse.data.overLimitUserIDList);
    console.log(imResponse.data.group);
    }).catch(function(imError) {
    console.warn('addGroupMember error:', imError);
    });

    踢人

    说明:
    1. 进阶版套餐包支持删除直播群群成员。您可以通过调用此接口实现直播群【封禁群成员】的效果。
    2. 踢出时长字段仅直播群(AVChatRoom)支持。
    3. 群成员被移除出直播群后,在踢出时长内如果用户想再次进群,需要 APP 管理员调用 RESTAPI 解封。过了踢出时长,用户可再次主动加入直播群。
    接口
    chat.deleteGroupMember(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    参数
    类型
    说明
    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); // 错误信息
    });

    获取群在线人数

    说明:
    调用此接口查询直播群人数的的频率建议控制在5~10秒一次;查询其它类型的群的在线人数限频60秒一次。
    接口
    chat.getGroupOnlineMemberCount(groupID);
    参数
    参数
    类型
    说明
    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); // 获取直播群在线人数失败的相关信息
    });
    
    联系我们

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

    技术支持

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

    7x24 电话支持