Obtaining All Groups in an App

Last updated: 2020-07-28 15:43:20

    Feature Description

    This API can be used by the app admin to obtain the IDs of all groups in an app.

    API Calling Description

    Applicable group types

    Instant Messaging (IM) provides the preceding multiple built-in group types. For details, see Group Systems.
    For details on custom group types, see Custom Group Types.

    Request URL example

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

    Request parameters

    The following table lists only the parameters to be modified when this API is called. For details on other parameters, see RESTful API Overview.

    Parameter Description
    v4/group_open_http_svc/get_appid_group_list The request API.
    sdkappid The SDKAppID assigned by the IM console when an app is created.
    identifier This must be the app admin account. For details, see App Admins.
    usersig The signature generated by the app admin account. For details, see Generating UserSig.
    random Enter a random 32-bit unsigned integer ranging from 0 to 4294967295.

    Maximum calling frequency

    The maximum calling frequency is 1 times per second.

    Request packet examples

    • Basic form
      If the total number of groups in the app exceeds 10,000, a maximum of 10,000 group IDs are returned. To obtain all group IDs, you must pull them by page.

      {}
    • Pulling by page
      You can use the Limit and Next fields to control pagination pulling:

      • The Limit field specifies the maximum number of groups in GroupIdList in the response packet, which cannot exceed 10,000.
      • The Next field is used to control pagination. For the initial pagination request, Next is set to 0. For subsequent requests, it is set to the previously returned Next value. If the returned Next value is 0, all groups have been pulled.
        For example, if pagination pulling is requested and 20 group IDs are displayed per page, the request parameters for the first page are {"Limit" : 20, "Next" : 0}, whereas those for the second page are {"Limit" : 20, "Next" : [Previously returned Next value]}, and so on.

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

      {
        "Limit": 1000,
        "Next": 0
      }
    • Specifying the group type
      You can specify the type of groups to be pulled, such as Public, Private, ChatRoom, AVChatRoom, or BChatRoom.

      {
        "GroupType" : "Public" // Specifies the type of groups to be pulled. If this parameter is not specified, all types of groups will be pulled.
      }
    • ALL IN ONE

      {
        "Limit": 1000,
        "Next": 0,
        "GroupType" : "Public" // Specifies the type of groups to be pulled. If this parameter is not specified, all types of groups will be pulled.
      }

    Request packet fields

    Field Type Attribute Description
    Limit Integer Optional The maximum number of group IDs to be obtained, which cannot exceed 10,000. If this field is not specified, the default is 10000.
    Next Integer Optional The pagination pulling flag when the number of groups is too large. It is initially set to 0 and subsequently to the Next value returned in the previous response. If the returned Next value is 0, all groups have been pulled.
    GroupType String Optional To obtain a specified type of groups, you can use GroupType for filtering. In this case, the returned TotalCount value indicates the total number of groups of the specified type in the app. If this field is not specified, all types of groups are obtained.
    Possible group types are Public, Private, ChatRoom, AVChatRoom, and BChatRoom.

    Response packet example

    {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "TotalCount": 2,
        "GroupIdList": [
            {
                "GroupId": "@TGS#2J4SZEAEL"
            },
            {
                "GroupId": "@TGS#2C5SZEAEF"
            }
        ],
        "Next": 4454685361
    }

    Response packet fields

    Field Type Description
    ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
    ErrorCode Integer The error code. 0: succeeded. Others: failed.
    ErrorInfo String Error information.
    TotalCount Integer The total number of existing groups in the app. To obtain a specified type of groups, you can use GroupType for filtering. In this case, the returned TotalCount value indicates the total number of groups of the specified type in the app. If this field is not specified, all types of groups are obtained.
    For example, assume that the app has total 50,000 groups, including 20,000 public groups. If GroupType in the request packet is set to Public, TotalCount in the response packet is 20,000 regardless of the Limit and Offset values. In addition, groups in GroupIdList are all public groups.
    GroupIdList Array The collection of obtained group IDs.
    Next Integer The pagination pulling flag.

    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, respectively.
    For common error codes (60000 to 79999), see Error Codes.
    The following table describes the error codes specific to this API.

    Error Code Description
    10002 An internal server error occurred. To correct it, try again.
    10004 A parameter is incorrect. To correct it, check request parameters such as GroupType based on the error description.
    10007 The operator does not have the necessary permissions for this operation. Only the app admin can call this API.
    10018 The response packet length exceeds the maximum packet length (1 MB) because the requested content is excessive. To correct it, reduce the amount of data requested at a time.

    API Commissioning Tool

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

    References

    Obtaining the list of groups a user has joined (v4/group_open_http_svc/get_joined_group_list)

    Was this page helpful?

    Was this page helpful?

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