Obtaining Profiles of Group Members

Feature Description

This API can be used by the app admin to obtain group member information based on the group ID.

API Commissioning Tool

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

API Calling Description

Applicable group types

Instant Messaging (IM) provides the preceding five built-in group types. For details, see Group Systems.

Due to differences in internal implementation, if the group type is AVChatRoom, information can be obtained only for up to 300 group members. For members who joined the group after the number of members reached 300, their information cannot be obtained. If the group type is BChatRoom, no group member information can be obtained.

Request URL example

https://console.tim.qq.com/v4/group_open_http_svc/get_group_member_info?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.

Maximum calling frequency

The maximum calling frequency is 200 times per second.

Request packet examples

• Basic form
  Obtains detailed group member information, including group member profiles and the custom fields of group members. The request contains only the group ID.

  {
    "GroupId":"@TGS#1NVTZEAE4"  // Group ID (required)
  }

• Pulling by page
  You can use the Limit and Offset fields to control pagination pulling:
  • The Limit field specifies the maximum number of members in the MemberList array in the response packet, which cannot exceed 6,000.
  • The Offset field specifies the sequence number of the starting group member for information pulling. For a pagination request (the page number starts from 1), the Offset value of each page is calculated as follows: (Page number – 1) × Number of group members displayed on each page.
    For example, if pagination pulling is requested and 20 group members are displayed on each page, request parameters for the first page are {"Limit" : 20, "Offset" : 0}, whereas those for the second page are {"Limit" : 20, "Offset" : 20}, and so on.

{
    "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
    "Limit": 100, // Maximum number of members whose information to be pulled
    "Offset": 0 // Sequence number of the starting group member whose information to be pulled
}

• Specifying information to be pulled
  You can use the MemberInfoFilter field to specify fields that you want to pull. Fields not specified in MemberInfoFilter will not be pulled.

  {
    "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
    "MemberInfoFilter": [ // Specifies the information to be obtained, where Member_Account is included by default. If this field is not specified, all group member information will be pulled.
        "Role",
        "JoinTime",
        "MsgSeq",
        "MsgFlag",
        "LastSendMsgTime",
        "ShutUpUntil",
        "NameCard"
    ]
  }

• Pulling the information of members with a specified role
  You can use the MemberRoleFilter field to specify the role of members whose information to be pulled. If this field is not specified, the information of members with any roles will be pulled.

  {
    "GroupId":"@TGS#37AB3PAEC", // Group ID (required)
    "MemberRoleFilter":[ // Member role filter
        "Owner",
        "Member"
    ]
  }

• Pulling the custom fields of a group member
  You can use the AppDefinedDataFilter_GroupMember field to specify the custom fields of group members to be pulled. Fields that are not specified in AppDefinedDataFilter_GroupMember will be ignored.

  {
    "GroupId":"@TGS#37AB3PAEC", // Group ID (required)
    "AppDefinedDataFilter_GroupMember": [ // Custom field filter for group members
        "MemberDefined2" // Key of the custom field
    ]
  }

• ALL IN ONE

  {
    "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
    "MemberInfoFilter": [ // Specifies the information to be obtained. If this field is not specified, all group member information will be pulled.
        "Role",
        "JoinTime",
        "MsgSeq",
        "MsgFlag",
        "LastSendMsgTime",
        "ShutUpUntil",
        "NameCard"
    ],
   "MemberRoleFilter":[ // Member role filter
        "Owner",
        "Member"
    ],
   "AppDefinedDataFilter_GroupMember": [ // Custom field filter for group members
        "MemberDefined2", // Key of the custom field
        "MemberDefined1"
    ],
    "Limit": 100, // Maximum number of members whose information to be pulled
    "Offset": 0 // Sequence number of the starting group member whose information to be pulled
  }

Request packet fields

Response packet examples

• Basic form and pagination pulling

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "MemberNum": 2, // Total number of members in the group
    "MemberList": [ // Group member list
        {
            "Member_Account": "bob",
            "Role": "Owner",
            "JoinTime": 1425976500, // Joining time of the member
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500, // Sending time of the last message
            "ShutUpUntil": 1431069882, // Muting expiry time (in seconds)
            "AppMemberDefinedData": [ // Member custom fields
                {
                   "Key": "MemberDefined1",
                   "Value": "ModifyDefined1"
                },
                {
                    "Key": "MemberDefined2",
                    "Value": "ModifyDefined2"
                }
             ]
        },
        {
            "Member_Account": "peter",
            "Role": "Member ",
            "JoinTime": 1425976500,
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500,
            "ShutUpUntil": 0, // The 0 value indicates that muting is disabled. Other values indicate the muting expiry time.
            "AppMemberDefinedData": [ // Member custom fields
                {
                   "Key": "MemberDefined1",
                   "Value": "ModifyDefined1"
                },
                {
                    "Key": "MemberDefined2",
                    "Value": "ModifyDefined2"
                }
             ]
        }
    ]
  }

• Pulling specified fields

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "MemberNum": 2, // Total number of members in the group
    "MemberList": [ // Group member list
        {
            "Member_Account": "bob",
            "Role": "Owner",
            "JoinTime": 1425976500, // Joining time of the member
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500, // Sending time of the last message
            "ShutUpUntil": 1431069882, // Muting expiry time (in seconds)
        },
        {
            "Member_Account": "peter",
            "Role": "Member ",
            "JoinTime": 1425976500,
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500,
            "ShutUpUntil": 0, // The 0 value indicates that muting is disabled. Other values indicate the muting expiry time.
        }
    ]
  }

• Pulling the information of members with a specified role

  {
    "ActionStatus": "OK", // Success is returned
    "ErrorCode": 0, // Return code
    "MemberList": [
        {
            "JoinTime": 1450680436, // Joining time of the member
            "LastSendMsgTime": 0, // Sending time of the last message
            "Member_Account": "Test_1", // Member account
            "MsgFlag": "AcceptNotNotify", // Type of member messages to be blocked
            "MsgSeq": 1, // Sequence number of the member’s read message
            "NameCard": "", // Member’s name card
            "Role": "Owner", // Member’s role
            "ShutUpUntil": 0 // The 0 value indicates that muting is disabled. Other values indicate the muting expiry time.
        },
        {
            "JoinTime": 1450680436,
            "LastSendMsgTime": 0,
            "Member_Account": "Test_6",
            "MsgFlag": "AcceptNotNotify",
            "MsgSeq": 1,
            "NameCard": "",
            "Role": "Admin",
            "ShutUpUntil": 0
        }
    ],
    "MemberNum": 8 // Total number of members in the group
  }

• Pulling the custom fields of a group member

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "MemberNum": 2, // Total number of members in the group
    "MemberList": [ // Group member list
        {
            "Member_Account": "bob",
            "Role": "Owner",
            "JoinTime": 1425976500, // Joining time of the member
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500, // Sending time of the last message
            "ShutUpUntil": 1431069882, // Muting expiry time (in seconds)
             "AppMemberDefinedData": [ // Member custom fields
                {
                    "Key": "MemberDefined2",
                    "Value": "ModifyDefined2"
                }
             ]
        },
        {
            "Member_Account": "peter",
            "Role": "Member",
            "JoinTime": 1425976500,
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500,
            "ShutUpUntil": 0, // The 0 value indicates that muting is disabled. Other values indicate the muting expiry time.
            "AppMemberDefinedData": [ // Member custom field
                {
                    "Key": "MemberDefined2",
                    "Value": "ModifyDefined2"
                }
             ]
        }
    ]
  }

• ALL IN ONE

  {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "MemberNum": 2, // Total number of members in the group
    "MemberList": [ // Group member list
        {
            "Member_Account": "bob",
            "Role": "Owner",
            "JoinTime": 1425976500, // Joining time of the member
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500, // Sending time of the last message
            "ShutUpUntil": 1431069882, // Muting expiry time (in seconds)
            "AppMemberDefinedData":[ // Member custom fields
                {
                   "Key":"MemberDefined1",
                   "Value": "ModifyDefined1"
                },
                {
                    "Key":"MemberDefined2",
                    "Value": "ModifyDefined2"
                }
             ]
        },
        {
            "Member_Account": "peter",
            "Role": "Member",
            "JoinTime": 1425976500,
            "MsgSeq": 1233,
            "MsgFlag": "AcceptAndNotify",
            "LastSendMsgTime": 1425976500,
            "ShutUpUntil": 0, // The 0 value indicates that muting is disabled. Other values indicate the muting expiry time.
            "AppMemberDefinedData": [ // Member custom fields
                {
                   "Key": "MemberDefined1",
                   "Value": "ModifyDefined1"
                },
                {
                    "Key": "MemberDefined2",
                    "Value": "ModifyDefined2"
                }
             ]
        }
    ]
  }

Response packet fields

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.

References

Modifying the profile of a group member (v4/group_open_http_svc/modify_group_member_info)