SDK 文档

服务端 API

获取用户所加入的群组

最近更新时间:2020-06-08 14:45:29

功能说明

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

接口调用说明

适用的群组类型

群组类型 ID 是否支持此 REST API
Private 支持,同新版本中的 Work(好友工作群),但默认不返回已加入但未激活的此类型群信息
Public 支持
ChatRoom 支持,同新版本中的 Meeting(临时会议群)
AVChatRoom 支持,但默认不返回此类型群信息

即时通信 IM 内置上述群组类型,详情介绍请参见 群组系统

请求 URL 示例

https://console.tim.qq.com/v4/group_open_http_svc/get_joined_group_list?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参考 REST API 简介

参数 说明
v4/group_open_http_svc/get_joined_group_list 请求接口
sdkappid 创建应用时即时通信 IM 控制台分配的 SDKAppID
identifier 必须为 App 管理员帐号,更多详情请参见 App 管理员
usersig App 管理员帐号生成的签名,具体操作请参见 生成 UserSig
random 请输入随机的32位无符号整数,取值范围0 - 4294967295

最高调用频率

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" // 入群时间
          ]
      }
    }
  • 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",
              "ShutUpAllMember"
          ],
          "SelfInfoFilter": [
              "Role", 
              "JoinTime",
              "MsgFlag", 
              "UnreadMsgNum" 
          ]
      }
    }

请求包字段说明

字段 类型 属性 说明
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(直播群),不填为拉取所有
ResponseFilter Object 选填 分别包含 GroupBaseInfoFilter 和 SelfInfoFilter 两个过滤器; GroupBaseInfoFilter 表示需要拉取哪些基础信息字段,详情请参阅 群组系统;SelfInfoFilter 表示需要拉取用户在每个群组中的哪些个人资料,详情请参阅 群组系统

应答包体示例

  • 基础形式和分页拉取
    {
      "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"
          }
      ]
    }
  • 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": 1,
              "Notification": "",
              "Owner_Account": "",
              "SelfInfo": {
                  "JoinTime": 1588148506,
                  "MsgFlag": "AcceptAndNotify",
                  "Role": "Member",
                  "UnreadMsgNum": 0
              },
              "ShutUpAllMember": "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 在线调试工具 调试本接口。

目录