获取用户所加入的群组

最近更新时间:2019-08-19 10:14:04

功能说明

App 管理员可以通过该接口获取某一用户加入的群组。

接口调用说明

适用的群组类型

群组类型 支持此 REST API
私有群(Private)
公开群(Public)
聊天室(ChatRoom)
音视频聊天室(AVChatRoom) 否(见说明)
在线成员广播大群(BChatRoom) 否(见说明)

即时通信 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位无符号整数

最高调用频率

100次/秒。如需提升调用频率,请根据 工单模板 提交工单申请处理。

请求包示例

  • 基础形式
    用来获取用户加入的群组,群组信息只包含所在群组的用户 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 和 ChatRoom(如果指定 AVChatRoom,获得的成员可能不完整)。

    {
      "Member_Account": "leckie",
      "GroupType": "Public" // 拉取哪种群组形态,不填为拉取所有
    }
  • 拉取指定信息
    可以指定拉取的基础信息字段,在 GroupBaseInfoFilter 中设置。
    可以指定拉取的群成员自身在群内的信息,在 SelfInfoFilter 中设置。

{
    "Member_Account": "leckie",
    "ResponseFilter": {
        "GroupBaseInfoFilter": [ // 需要哪些基础信息字段
            "Type",
            "Name",
            "Introduction",
            "Notification",
            "FaceUrl",
            "CreateTime",
            "Owner_Account",
            "LastInfoTime",
            "LastMsgTime",
            "NextMsgSeq",
            "MemberNum",
            "MaxMemberNum",
            "ApplyJoinOption",
            "ShutUpAllMember"
        ],
        "SelfInfoFilter": [ // 需要自身在群内的信息
            "Role", // 群内身份
            "JoinTime", // 入群时间
            "MsgFlag", // 消息屏蔽类型
            "UnreadMsgNum" // 未读消息数量(即时通信 IM 后台计算得出)
        ]
    }
}
  • ALL IN ONE
    {
      "Member_Account": "leckie",
      "Limit": 10, // 拉取多少个,不填标识拉取全部
      "Offset": 0, // 从第多少个开始拉取
      "GroupType": "Public", // 拉取哪种群组形态,不填为拉取所有
      "ResponseFilter": {
          "GroupBaseInfoFilter": [ // 需要哪些基础信息字段,含义参见“基本字段介绍”
              "Type",
              "Name",
              "Introduction",
              "Notification",
              "FaceUrl",
              "CreateTime",
              "Owner_Account",
              "LastInfoTime",
              "LastMsgTime",
              "NextMsgSeq",
              "MemberNum",
              "MaxMemberNum",
              "ApplyJoinOption",
              "ShutUpAllMember"
          ],
          "SelfInfoFilter": [ // 自身在群内的信息
              "Role", // 群内身份
              "JoinTime", // 入群时间
              "MsgFlag", // 消息屏蔽类型
              "UnreadMsgNum" // 未读消息数量(即时通信 IM 后台计算得出)
          ]
      }
    }

请求包字段说明

字段 类型 属性 说明
Member_Account String 必填 需要查询的用户帐号
Limit Integer 选填 单次拉取的群组数量,如果不填代表所有群组,分页方式与 获取 App 中的所有群组 相同
Offset Integer 选填 从第多少个群组开始拉取,分页方式与 获取 App 中的所有群组 相同
GroupType String 选填 拉取哪种群组形态,例如Private,Public,ChatRoom 或 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#2J4SZEAEL",
              "Type": "Public",
              "LastMsgTime": 1425976500,
              "MemberCount": 48,
              "ShutUpAllMember": "On",
              "SelfInfo": {
                  "Role": "Owner",
                  "MsgFlag": "AcceptAndNotify",
                  "UnreadMsgNum": 1
              }
          },
          {
              "GroupId": "@TGS#2C5SZEAEF",
              "Type": "ChatRoom",
              "LastMsgTime": 1425976567,
              "MemberCount": 120,
              "ShutUpAllMember": "Off",
              "SelfInfo": {
                  "Role": "Member",
                  "MsgFlag": "AcceptAndNotify",
                  "UnreadMsgNum": 0
              }
          }
      ]
    }
  • ALL IN ONE
    {
      "ActionStatus": "OK",
      "ErrorInfo": "",
      "ErrorCode": 0,
      "TotalCount": 1, // 不论 Limit 和 Offset 如何设置,该值总是满足条件的群组总数
      "GroupIdList": [
          {
              "GroupId": "@TGS#2J4SZEAEL",
              "Type": "Public",
              "LastMsgTime": 1425976500,
              "MemberCount": 48,
              "SelfInfo": {
                  "Role": "Owner",
                  "MsgFlag": "AcceptAndNotify",
                  "UnreadMsgNum": 1
              }
          }
      ]
    }

应答包字段说明

字段 类型 说明
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 在线调试工具 调试本接口。

参考

获取 App 中的所有群组(v4/group_open_http_svc/get_appid_group_list)。