Obtaining the Groups a User Has Joined

Last updated: 2020-07-06 16:40:43

    Feature Description

    This API is used by app admins to obtain the list of groups a certain user has joined. The information of work groups (Work) and livestreaming groups (AVChatRoom) that the user has joined but are not activated is not pulled by default.

    API Calling Description

    Applicable group types

    Group Type ID Is this RESTful API Supported?
    Private Yes. Same as Work (work group for friends) in the new version. The information work groups that the user has joined but are not activated is not returned by default.
    Public Yes.
    ChatRoom Yes. Same as Meeting (temporary meeting group) in the new version.
    AVChatRoom Yes. The information of AVChatRooms that the user has joined is not returned by default.

    These are the 4 built-in group types in IM. For detailed information, see the Group System.

    Sample 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 list below contains only the parameters commonly used when calling this API and their descriptions. For more parameters, see RESTful API Overview.

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

    Maximum calling frequency

    The maximum calling frequency is 200 calls per second.

    Sample request packet

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

      {
        "Member_Account": "leckie"
      }
    • Pagination pull
      You can use the Limit and Offset fields to control the pagination mode:

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

      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, all groups will be pulled.
        "Offset": 0 // Specifies the sequence number of the group starting from which the information is pulled.
      }
    • Specify the group type
      You can specify the type of groups to be pulled, for example, Public (social networking group for strangers), Private (work group for friends, same as Work in the new version), and ChatRoom (meeting group, same as Meeting in the new version). If AVChatRoom (livestreaming group) is specified, you may obtain an incomplete list of members.

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

      {
        "Member_Account": "leckie",
        "WithHugeGroups":1, // Supports pulling the information of AVChatRoom groups (livestreaming groups).
        "WithNoActiveGroups":1,// Supports pulling the information of Private (work group for friends, same as Work in the new version) groups that the user has joined but are not activated.
        "Limit": 10, // Specifies the number of groups to be pulled. If this field is not specified, all groups will be pulled.
        "Offset": 0, // Specifies the sequence number of the group starting from which the information is pulled.
        "ResponseFilter": {
            "GroupBaseInfoFilter": [ // Specifies basic information fields to be pulled.
                "Type",
                "Name",
                "Introduction",
                "Notification"
            ],
            "SelfInfoFilter": [ // Specifies your own information in the group.
                "Role", // Role in the group
                "JoinTime" // Time when 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 Required Description
    Member_Account String Required User account to be queried
    WithHugeGroups Integer Optional Whether to obtain the list of AVChatRoom groups the user has joined. 0 (default): no, 1: yes.
    WithNoActiveGroups Integer Optional Whether to obtain the list of Private groups (work group for friends, same as Work in the new version) that the user has joined but are not activated. 0 (default): no, 1: yes.
    Limit Integer Optional Number of groups to be pulled in a single request. If this parameter is not specified, all groups are pulled.
    Offset Integer Optional Sequence number of the group starting from which the information is pulled
    GroupType String Optional Types of groups to pull, for example, Public (social networking group for strangers), Private (work group for friends, same as Work in the new version), ChatRoom (meeting group, same as Meeting in the new version), or AVChatRoom (livestreaming group). If this parameter is not specified, all types of groups are pulled.
    ResponseFilter Object Optional This includes two filters: GroupBaseInfoFilter and SelfInfoFilter. GroupBaseInfoFilter specifies the basic information fields to be pulled. For details, see the Group System. SelfInfoFilter specifies whether to pull the operator’s own information in each group. For details, see the Group System.

    Sample response packet body

    • Basic form and pagination
      {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "TotalCount": 2, // This value is the total number of groups that meet the conditions, regardless of the Limit and Offset settings.
        "GroupIdList": [
            {
                "GroupId": "@TGS#2J4SZEAEL"
            },
            {
                "GroupId": "@TGS#2C5SZEAEF"
            }
        ]
      }
    • Specify the group type
      {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "TotalCount": 1,
        "GroupIdList": [
            {
                "GroupId": "@TGS#2J4SZEAEL"
            }
        ]
      }
    • Pull the 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, // This value is the total number of groups that meet the conditions, regardless of the Limit and Offset settings.
        "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 Result of the request. OK indicates that the request was successful, and FAIL indicates that the request failed.
    ErrorCode Integer Error code. 0 indicates that the request was successful, and any non-zero value indicates that the request failed.
    ErrorInfo String Detailed error information
    TotalCount Integer Number of groups that the user has joined
    GroupIdList Array Information of the groups that are pulled. The returned result is the information filtered based on the filtering fields set in the filter. For more information on the fields, see the Group Data Structure.

    Error Codes

    Unless a network error (such as error 502) occurs, the returned HTTP status code for this API is always 200. The specific error code and details can be found in the response packet fields such as ErrorCode and ErrorInfo.
    For public error codes (60000 to 79999), see Error Codes.
    The list below contains error codes specific to this API:

    Error Code Description
    10002 A system error occurred. Please try again or contact our technical support.
    10003 The request command is invalid. Please try again or contact our 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.

    API Debugging Tool

    Use the online debugging tool for RESTful APIs to debug this API.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help