tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    获取用户所加入的群组

    最后更新时间：2023-12-14 10:30:30
    下载PDF

      功能说明

      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
      孟买：adminapiind.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 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款