即时通信 IM
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 即时通信 IM > 服务端 API > REST API > 群组相关 > 群组管理 > 获取用户所加入的群组

获取用户所加入的群组

最近更新时间：2023-12-12 15:56:27

我的收藏

本页目录：

功能说明

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 在线调试工具 调试本接口。
中国站