tencent cloud

文档反馈

获取用户所加入的群组

最后更新时间:2024-07-16 11:15:59

    功能说明

    App 管理员可以通过本接口获取某一用户加入的群信息。默认不获取用户已加入但未激活好友工作群(Work)以及直播群(AVChatRoom)群信息。

    接口调用说明

    适用的群组类型

    群组类型 ID
    是否支持此 REST API
    Private
    支持,同新版本中的 Work(好友工作群),但默认不返回已加入但未激活的此类型群信息
    Public
    支持
    ChatRoom
    支持,同新版本中的 Meeting(临时会议群)
    AVChatRoom
    支持,但默认不返回此类型群信息。如果指定拉取 AVChatRoom 类型群信息,获得的群信息可能不完整,AVChatRoom 并不存储所有的群成员资料。
    Community(社群)
    支持
    即时通信 IM 内置上述群组类型,详情介绍请参见 群组系统

    请求 URL 示例

    https://xxxxxx/v4/group_open_http_svc/get_joined_group_list?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

    请求参数说明

    下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参见 REST API 简介
    参数
    说明
    xxxxxx
    SDKAppID 所在国家/地区对应的专属域名:
    中国:console.tim.qq.com
    新加坡:adminapisgp.im.qcloud.com
    首尔: adminapikr.im.qcloud.com
    法兰克福:adminapiger.im.qcloud.com
    
    硅谷:adminapiusa.im.qcloud.com
    雅加达:adminapiidn.im.qcloud.com
    v4/group_open_http_svc/get_joined_group_list
    请求接口
    sdkappid
    创建应用时即时通信 IM 控制台分配的 SDKAppID
    identifier
    必须为 App 管理员账号,更多详情请参见 App 管理员
    usersig
    App 管理员账号生成的签名,具体操作请参见 生成 UserSig
    random
    请输入随机的32位无符号整数,取值范围0 - 4294967295
    contenttype
    请求格式固定值为json

    最高调用频率

    200次/秒。

    请求包示例

    基础形式。
    用来获取用户加入的群组,群组信息只包含所在群组的用户 ID。
    {
    "Member_Account": "leckie"
    }
    分页拉取。
    可以使用 Limit 和 Offset 两个值用于控制分页拉取:
    Limit 限制回包中 GroupIdList 数组中群组的个数,不得超过5000。
    Offset 控制从整个群组列表中的第多少个开始读取(默认从0开始)。对于分页请求(页码数字从1开始),每一页的 Offset 值应当为:(页码数– 1)×每页展示的群组数量。 例如:假设需要分页拉取,每页展示20个,则第一页的请求参数应当为:{“Limit”: 20, “Offset”: 0},第二页的请求参数应当为{“Limit”: 20, “Offset”: 20},依此类推。
    Limit 或者 Offset 的取值不会对应答包体中的 TotalCount 造成影响。
    {
    "Member_Account": "leckie",
    "Limit": 10, // 拉取多少个,不填标识拉取全部
    "Offset": 0 // 从第多少个开始拉取
    }
    指定群组形态。
    可以指定所拉取的群组所属的群组类型,例如 Public(陌生人社交群),Private(同新版本 Work,好友工作群)和 ChatRoom(同新版本 Meeting,会议群),如果指定 AVChatRoom(直播群),获得的成员可能不完整。
    {
    "Member_Account": "leckie",
    "GroupType": "Public" // 拉取哪种群组类型,不填为拉取所有
    }
    拉取指定信息。
    可以指定拉取的基础信息字段,在 GroupBaseInfoFilter 中设置。
    可以指定拉取的群成员自身在群内的信息,在 SelfInfoFilter 中设置。
    {
    "Member_Account": "leckie",
    "WithHugeGroups":1, //支持拉取 AVChatRoom(直播群)信息
    "WithNoActiveGroups":1,//支持拉取已加入但未激活的 Private(即新版本中 Work,好友工作群) 信息
    "Limit": 10, // 拉取多少个,不填标识拉取全部
    "Offset": 0, // 从第多少个开始拉取
    "ResponseFilter": {
    "GroupBaseInfoFilter": [ // 需要哪些基础信息字段
    "Type",
    "Name",
    "Introduction",
    "Notification"
    ],
    "SelfInfoFilter": [ // 需要自身在群内的信息
    "Role", // 群内身份
    "JoinTime" // 入群时间
    ]
    }
    }
    
    拉取支持话题的社群。
    {
    "Member_Account": "107867", // 需要查询的用户账号(必填)
    "SupportTopic": 1 // 指定查询的群类型是否支持话题,仅社群类型支持此字段
    }
    ALL IN ONE。
    {
    "Member_Account": "leckie",
    "WithHugeGroups":1,
    "WithNoActiveGroups":1,
    "ResponseFilter": {
    "GroupBaseInfoFilter": [
    "Type",
    "Name",
    "Introduction",
    "Notification",
    "FaceUrl",
    "CreateTime",
    "Owner_Account",
    "LastInfoTime",
    "LastMsgTime",
    "NextMsgSeq",
    "MemberNum",
    "MaxMemberNum",
    "ApplyJoinOption",
    "MuteAllMember"
    ],
    "SelfInfoFilter": [
    "Role",
    "JoinTime",
    "MsgFlag",
    "MsgSeq"
    ]
    }
    }

    请求包字段说明

    字段
    类型
    属性
    说明
    Member_Account
    String
    必填
    需要查询的用户账号
    WithHugeGroups
    Integer
    选填
    是否获取用户加入的 AVChatRoom(直播群),0表示不获取,1表示获取。默认为0
    WithNoActiveGroups
    Integer
    选填
    是否获取用户已加入但未激活的 Private(即新版本中 Work,好友工作群)群信息,0表示不获取,1表示获取。默认为0
    Limit
    Integer
    选填
    单次拉取的群组数量,如果不填代表所有群组
    Offset
    Integer
    选填
    从第多少个群组开始拉取
    GroupType
    String
    选填
    拉取哪种群组类型,例如 Public(陌生人社交群),Private(即新版本Work,好友工作群),ChatRoom (即新版本Meeting,会议群),AVChatRoom(直播群),Community(社群),不填为拉取所有
    ResponseFilter
    Object
    选填
    分别包含 GroupBaseInfoFilter 和 SelfInfoFilter 两个过滤器; GroupBaseInfoFilter 表示需要拉取哪些基础信息字段,详情请参见 群组系统;SelfInfoFilter 表示需要拉取用户在每个群组中的哪些个人资料,详情请参见 群组系统
    SupportTopic
    Integer
    选填
    指定查询的是否为支持话题的群组,1表示支持,0表示不支持。如果指定了此字段,则 GroupType 字段必须为 Community

    应答包体示例

    基础形式和分页拉取。
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TotalCount": 2, // 不论Limit和Offset如何设置,该值总是满足条件的群组总数
    "GroupIdList": [
    {
    "GroupId": "@TGS#2J4SZEAEL"
    },
    {
    "GroupId": "@TGS#2C5SZEAEF"
    }
    ]
    }
    指定群组类型。
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TotalCount": 1,
    "GroupIdList": [
    {
    "GroupId": "@TGS#2J4SZEAEL"
    }
    ]
    }
    拉取指定信息。
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TotalCount": 2,
    "GroupIdList": [
    {
    "GroupId": "@TGS#16UMONKGG",
    "Introduction": "",
    "Name": "d",
    "Notification": "",
    "SelfInfo": {
    "JoinTime": 1588148506,
    "Role": "Member"
    },
    "Type": "Private"
    },
    {
    "GroupId": "@TGS#3FCOX2MGW",
    "Introduction": "",
    "Name": "TestGroup",
    "Notification": "",
    "SelfInfo": {
    "JoinTime": 1588041114,
    "Role": "Member"
    },
    "Type": "ChatRoom"
    }
    ]
    }
    拉取支持话题的社群。
    {
    "ActionStatus": "OK",
    "ErrorInfo": "ok",
    "ErrorCode": 0,
    "TotalCount": 1,
    "GroupIdList": [
    {
    "GroupId": "@TGS#_@TGS#cMOQ7HIM62CD",
    "Type": "Community",
    "SupportTopic": 1,
    "GrossTopicNextMsgSeq": 3,
    "SelfInfo": {
    "GrossTopicReadSeq": 2
    }
    }
    ]
    }
    
    ALL IN ONE。
    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TotalCount": 1, // 不论 Limit 和 Offset 如何设置,该值总是满足条件的群组总数
    "GroupIdList": [
    {
    "ApplyJoinOption": "DisableApply",
    "CreateTime": 1585718204,
    "FaceUrl": "",
    "GroupId": "@TGS#16UMONKGG",
    "Introduction": "",
    "LastInfoTime": 1588148506,
    "LastMsgTime": 0,
    "MaxMemberNum": 200,
    "MemberNum": 1,
    "Name": "d",
    "NextMsgSeq": 2,
    "Notification": "",
    "Owner_Account": "",
    "SelfInfo": {
    "JoinTime": 1588148506,
    "MsgFlag": "AcceptAndNotify",
    "Role": "Member",
    "MsgSeq": 1
    },
    "MuteAllMember": "Off",
    "Type": "Private"
    }
    ]
    }

    应答包字段说明

    字段
    类型
    说明
    ActionStatus
    String
    请求处理的结果,OK 表示处理成功,FAIL 表示失败
    ErrorCode
    Integer
    错误码,0表示成功,非0表示失败
    ErrorInfo
    String
    错误信息
    TotalCount
    Integer
    用户所加入的群组个数
    GroupIdList
    Array
    拉取到的群组信息,返回的结果是根据过滤器中设置的过滤字段进行过滤后的信息,字段详情请参见 群组数据结构介绍

    错误码说明

    除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
    公共错误码(60000到79999)参见 错误码
    本 API 私有错误码如下:
    错误码
    含义说明
    10002
    系统错误,请再次尝试或联系技术客服
    10003
    请求命令非法,请再次尝试或联系技术客服
    10004
    参数非法。请根据应答包中的 ErrorInfo 字段,检查必填字段是否填充,或者字段的填充是否满足协议要求
    10018
    应答包长度超限。因为请求的内容过多,导致应答包超过了最大包长(1MB),请尝试减少单次请求的数据量

    接口调试工具

    通过 REST API 在线调试工具 调试本接口。
    联系我们

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

    技术支持

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

    7x24 电话支持