Obtaining Detailed Group Profiles

Last updated: 2020-05-22 16:33:45

    Feature Description

    This API is used by the app admin to query detailed group information based on the group ID.

    Call Description

    Applicable group types

    Group Type Support for This RESTful API
    Private group Yes
    Public group Yes
    Chat room Yes
    Audio-video chat room Yes
    Broadcasting chat room Yes

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

    Example request URL

    https://console.tim.qq.com/v4/group_open_http_svc/get_group_info?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_group_info 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 following example is used to obtain the detailed group information, including all the basic group information, group member information, and custom information. The request only contains a list of group IDs. Each request can be used to query information on a maximum of 50 groups.

      {
        "GroupIdList": [ // Group ID list (required)
            "@TGS#1NVTZEAE4",
            "@TGS#1CXTZEAET"
        ]
      }
    • Pulling specified information

      • To specify the basic information fields to be pulled, set GroupBaseInfoFilter.
      • To specify the member information fields to be pulled, set MemberInfoFilter.
      • To specify the group-specific custom fields to be pulled, set AppDefinedDataFilter_Group. This field is unavailable by default and must be enabled additionally. For more information, see "Request packet fields".
      • To specify the group member-specific custom fields to be pulled, set AppDefinedDataFilter_GroupMember. This field is unavailable by default and must be enabled additionally. For more information, see "Request packet fields".

      If filters are set, only the fields specified by filters are pulled.

      {
        "GroupIdList": [ // Group ID list (required)
            "@TGS#1NVTZEAE4",
            "@TGS#1CXTZEAET"
        ],
        "ResponseFilter": { // The filters that you specify for the response.
            "GroupBaseInfoFilter": [ // Add this array if you want to query the basic information.
                "Type",
                "Name",
                "Introduction",
                "Notification"
            ],
            "MemberInfoFilter": [ // Add this array if you want to query the member information.
                "Account", // Member ID
                Role
            ],
            "AppDefinedDataFilter_Group": [ // The filter for group-specific custom fields. This filter is disabled by default.
                "GroupTestData1",
                "GroupTestData2"
            ],
            "AppDefinedDataFilter_GroupMember": [ // The filter for group member-specific custom fields. This filter is disabled by default.
                "MemberDefined2",
                "MemberDefined1"
            ]
        }
      }

    Request packet fields

    Field Type Property Description
    GroupIdList Array Required The list of group IDs that you specify for the query.
    ResponseFilter Object Optional It contains three filters: GroupBaseInfoFilter, MemberInfoFilter, and AppDefinedDataFilter_Group.
    GroupBaseInfoFilter Array Optional The basic information field filter, which specifies the basic information fields to query. For more information, see Group basic data.
    MemberInfoFilter Array Optional The member information field filter, which specifies the member information fields to query. For more information, see Group member information.
    AppDefinedDataFilter_Group Array Optional The group-specific custom field filter, which specifies the group-specific custom fields to query. For more information, see Custom fields.
    AppDefinedDataFilter_GroupMember Array Optional The group member-specific custom field filter, which specifies the group member-specific custom fields to query. For more information, see Custom fields.

    Example response packet body

    • Basic form
      {
        "ActionStatus":"OK",
        "ErrorInfo": "", // The ErrorInfo parameter here is meaningless. You need to check the ErrorInfo parameter of each group.
        "ErrorCode": 0, // The ErrorCode parameter here is meaningless. You need to check the ErrorCode parameter of each group.
        "GroupInfo": [ // A group information array is returned. Only one group is listed here for simplicity.
            {
                "GroupId": "@TGS#2J4SZEAEL",
                "ErrorCode": 0, // The result specific to this group.
                "ErrorInfo": "" , // The result specific to this group.
                "Type": "Public", // The group type.
                "Name": "MyFirstGroup", // The group name.
                "Appid":1400001001,// The SDKAppID of the IM application.
                "Introduction": "TestGroup", // Group introduction.
                "Notification": "TestGroup", // Group notification.
                "FaceUrl": "http://this.is.face.url", // The group profile photo.
                "Owner_Account": "leckie", // The group owner ID.
                "CreateTime": 1426976500, // The group creation time in UTC.
                "LastInfoTime": 1426976500, // The UTC time when the group information was last updated.
                "LastMsgTime": 1426976600, // The UTC time when the last message in the group was sent.
                "NextMsgSeq": 1234,
                "MemberNum": 2, // The current number of members in the group.
                "MaxMemberNum": 50, // The maximum number of members in the group.
                "ApplyJoinOption": "FreeAccess", // The method for handling requests to join the group.
                "ShutUpAllMember": "On", // All members in the group are muted.
                "AppDefinedData": [ // Group-specific custom fields.
                    {
                        "Key": "GroupTestData1", // Key of the custom field.
                        "Value": "xxxx" // Value of the custom field.
                    },
                    {
                        "Key": "GroupTestData2",
                        "Value": "abc\u0000\u0001" // Custom fields support binary data.
                    }
                ],
                "MemberList": [ // The group member list.
                    {
                        "Member_Account": "leckie", // The member ID.
                        "Role": "Owner", // The role of the member in the group.
                        "JoinTime": 1425976500, // The UTC time when the member joined the group.
                        "MsgSeq": 1233,
                        "MsgFlag": "AcceptAndNotify", // Indicates whether the member blocks group messages.
                        "LastSendMsgTime": 1425976500, // The last time in UTC when the member sent a message in the group.
                        "ShutUpUntil": 1431069882, // The UTC time when the muting period for the member expires.
                        "AppMemberDefinedData": [ // Group member-specific custom fields.
                            {
                                 "Key": "MemberDefined1",
                                 "Value": "ModifyDefined1"
                            },
                            {
                                 "Key": "MemberDefined2",
                                 "Value": "ModifyDefined2"
                            }
                        ]
                    },
                    {
                        "Member_Account": "peter",
                        "Role": "Member",
                        "JoinTime": 1425976500, // The time when the member joined the group.
                        "MsgSeq": 1233,
                        "MsgFlag": "AcceptAndNotify",
                        "LastSendMsgTime": 1425976500, // The last time when the member sent a message.
                        "ShutUpUntil": 0, // The value 0 indicates that the member is not muted, and other values indicate the time when the member will be unmuted.
                        "AppMemberDefinedData":[ // Group member-specific custom fields.
                            {
                                "Key": "MemberDefined1",
                                "Value": "ModifyDefined1"
                            },
                            {
                                "Key": "MemberDefined2",
                                "Value": "ModifyDefined2"
                            }
                         ]
                    }
                ]
            }
        ]
      }
    • Pulling specified information
      {
        "ActionStatus": "OK",
        "ErrorInfo": "", // The ErrorInfo parameter here is meaningless. You need to check the ErrorInfo parameter of each group.
        "ErrorCode": 0, // The ErrorCode parameter here is meaningless. You need to check the ErrorCode parameter of each group.
        "GroupInfo": [ // A group information array is returned. Only one group is listed here for simplicity.
            {
                "GroupId": "@TGS#2J4SZEAEL",
                "ErrorCode": 0, // The result specific to this group.
                "ErrorInfo":"" , // The result specific to this group.
                "Type": "Public", // The group type.
                "Name": "MyFirstGroup", // The group name.
                "Introduction": "TestGroup", // Group introduction.
                "Notification": "TestGroup", // Group notification.
                "AppDefinedData": [ // Group-specific custom fields.
                    {
                        "Key": "GroupTestData1", // Key of the custom field.
                        "Value": "xxxx" // Value of the custom field.
                    },
                    {
                        "Key": "GroupTestData2",
                        "Value": "abc\u0000\u0001" // Custom fields support binary data.
                    }
                ],
                "MemberList": [ // The group member list.
                    {
                        "Member_Account": "leckie", // The member ID.
                        "Role": "Owner", // The role of the member in the group.
                        "AppMemberDefinedData":[ // Group member-specific custom fields.
                            {
                                "Key":" MemberDefined1",
                                "Value":" ModifyDefined1"
                            },
                            {
                                "Key":" MemberDefined2",
                                "Value":" ModifyDefined2"
                            }
                         ]
                    },
                    {
                        "Member_Account": "peter",
                        "Role": "Member",
                        "AppMemberDefinedData":[ // Group member-specific custom fields.
                            {
                                "Key":" MemberDefined1",
                                "Value":" ModifyDefined1"
                            },
                            {
                                "Key":" MemberDefined2",
                                "Value":" ModifyDefined2"
                            }
                         ]
                    }
                ]
            }
        ]
      }

    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.
    GroupInfo Array The group information array is returned, including basic group information fields, group member information fields, group-specific custom fields, and group member-specific custom fields. 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.
    10007 Insufficient operation permissions. Check whether the operator is the app admin.
    10010 The group does not exist or once existed but has been disbanded.
    10015 The group ID is invalid. Check whether the group ID is specified correctly.
    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.

    References

    Was this page helpful?

    Was this page helpful?

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