Obtaining the Groups a User has Joined

Last updated: 2020-05-27 16:10:01

PDF

Feature Description

This API can be used by the app admin to obtain information about the public groups, chat rooms, and activated private groups that a user has joined. By default, this API cannot be used to obtain information on unactivated private groups, audio-video chat rooms, and broadcasting chat rooms that the user has joined.

Call Description

Applicable group types

Group Type Support for This RESTful API
Private group Yes. By default, this API only returns information on activated private groups.
Public group Yes
Chat room Yes
Audio-video chat room Yes. By default, this API does not return information on audio-video chat rooms.
Broadcasting chat room Yes. By default, this API does not return information on broadcasting chat rooms.

IM supports the preceding five group types. For more information, see Group System.

Example request 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

Request parameters

The following table only describes the parameters that are modified when this API is called. For more information on other parameters, see RESTful API Overview.

Parameter Description
v4/group_open_http_svc/get_joined_group_list The request API.
sdkappid The SDKAppID assigned by the IM console when an application is created.
identifier The value must be the app admin account. For more information, see App Admin.
usersig The signature generated by the app admin account. For more information on the operation, see Generating UserSig.
random A random 32-bit unsigned integer ranging from 0 to 4294967295.

Maximum call frequency

200 times/second

Example request packet

  • Basic form
    The request in basic form is used to obtain information on groups that a user has joined. The group information only contains the IDs of the user in the groups.

    {
      "Member_Account": "leckie"
    }
  • Pulling by page
    You can use the Limit and Offset fields to control pulling by page:

    • Limit specifies the maximum number of groups in the GroupIdList array in the response packet, which cannot exceed 5000.
    • Offset specifies the sequence number of the group in the entire group list, starting from which information is read. Offset is 0 by default. If paging is requested (the page number starts from 1), the Offset value of each page should be (Page number – 1) x Number of groups displayed on each page.
      For example, pulling by page is needed and 20 groups are displayed on each page. The request parameter for the first page should be {"Limit": 20, "Offset": 0}, and the request parameter for the second page should be {"Limit": 20, "Offset": 20}.

    The value of Limit or Offset does not affect TotalCount in the response packet.

    {
      "Member_Account": "leckie",
      "Limit": 10, // Specifies the number of groups to be pulled. If this field is not specified, information on all groups will be pulled.
      "Offset": 0 // Specifies the sequence number of the group starting from which information is pulled.
    }
  • Specifying the group type
    You can specify the type of groups to be pulled, such as Public, Private, and ChatRoom. If the specified group type is AVChatRoom, the obtained member information may be incomplete.

    {
      "Member_Account": "leckie",
      "GroupType": "Public" // Specifies the type of groups to be pulled. If this parameter is not specified, information on all groups will be pulled.
    }
  • Pulling specified information
    To specify the basic information fields to be pulled, set GroupBaseInfoFilter.
    To specify the group member information in a group that needs to be pulled, set SelfInfoFilter.

    {
      "Member_Account": "leckie",
      "WithHugeGroups":1, // Supports pulling information on audio-video chat rooms and broadcasting chat rooms.
      "WithNoActiveGroups":1,// Supports pulling information on unactivated private groups that the user has joined.
      "Limit": 10, // Specifies the number of groups to be pulled. If this field is not specified, information on all groups will be pulled.
      "Offset": 0, // Specifies the sequence number of the group starting from which information is pulled.
      "ResponseFilter": {
          "GroupBaseInfoFilter": [ // Specifies the basic information fields to be pulled.
              "Type",
              "Name",
              "Introduction",
              "Notification"
          ],
          "SelfInfoFilter": [ // Specifies information on the user in the group.
              "Role", // The role in the group.
              "JoinTime", // The time that the member joined the group.
          ]
      }
    }
  • 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" 
          ]
      }
    }

Request packet fields

Field Type Property Description
Member_Account String Required The user account to query.
WithHugeGroups Integer Optional Specifies whether to obtain information on audio-video chat rooms and broadcasting chat rooms that the user has joined. 0: no. 1: yes. The default value is 0.
WithNoActiveGroups Integer Optional Specifies whether to obtain information on unactivated private groups that the user has joined. 0: no. 1: yes. The default value is 0.
Limit Integer Optional The number of groups pulled at a time. If this field is not specified, information on all groups will be pulled.
Offset Integer Optional The sequence number of the group starting from which the information is pulled.
GroupType String Optional The type of groups to be pulled. Values include Private, Public, ChatRoom, and AVChatRoom. If this field is not specified, information on all groups will be pulled.
ResponseFilter Object Optional It includes two filters: GroupBaseInfoFilter and SelfInfoFilter. GroupBaseInfoFilter specifies the basic information fields to be pulled. For more information, see Group System. SelfInfoFilter specifies the personal information of a user to be pulled in each group. For more information, see Group System.

Example response packet body

  • Basic form and pulling by page
    {
      "ActionStatus":"OK",
      "ErrorInfo":"",
      "ErrorCode": 0,
      "TotalCount": 2, // The value is the total number of groups that meet the conditions, regardless of the Limit and Offset values.
      "GroupIdList": [
          {
              "GroupId": "@TGS#2J4SZEAEL"
          },
          {
              "GroupId": "@TGS#2C5SZEAEF"
          }
      ]
    }
  • Specifying the group type
    {
      "ActionStatus":"OK",
      "ErrorInfo":"",
      "ErrorCode": 0,
      "TotalCount": 1,
      "GroupIdList": [
          {
              "GroupId": "@TGS#2J4SZEAEL"
          }
      ]
    }
  • Pulling specified information
    {
      "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, // The value is the total number of groups that meet the conditions, regardless of the Limit and Offset values.
      "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"
          }
      ]
    }

Response packet fields

Field Type Description
ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
ErrorCode Integer The error code. 0: succeeded. Other values: failed.
ErrorInfo String The error information.
TotalCount Integer The number of groups that the user has joined.
GroupIdList Array Pulled group information. The return result is the information filtered based on the fields set in the filter. For more information on the fields, see Group Data Structure.

Error Codes

Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200. ErrorCode and ErrorInfo in the response packet represent the actual error code and error information.
For public error codes 60000 to 79999, see Error Codes.
The following table describes the error codes specific to this API.

Error Code Description
10002 A system error occurred. Please try again or contact technical support.
10003 The request command is invalid. Please try again or contact technical support.
10004 A parameter is invalid. Based on the ErrorInfo field in the response packet, check whether the required fields have been specified or whether the fields are set according to protocol requirements.
10018 The response packet length exceeds the maximum packet length of 1 MB because too much content was requested. Try to reduce the amount of data requested at a time.

Commissioning Tool

Use the RESTful API online commissioning tool to commission this API.