Obtaining Profiles of Group Members

Last updated: 2020-03-24 15:29:53

PDF

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

Group Type Support This RESTful API
Private Yes
Public Yes
ChatRoom Yes
AVChatRoom Yes for no more than 300 members (see description below)
BChatRoom No (see description below)

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.

Parameter Description
v4/group_open_http_svc/get_group_member_info 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 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

Field Type Attribute Description
GroupId String Required The ID of the group, for which member information needs to be obtained.
MemberInfoFilter Array Optional The information to be obtained. If this field is not specified, all group member information will be pulled. For details on group member information fields, see Group Member Profiles.
MemberRoleFilter Array Optional The filter for specifying group members with a specified role. If this field is not specified, the information of members with any role will be pulled. Possible member roles are "Owner", "Admin", and "Member".
AppDefinedDataFilter_GroupMember Array Optional This field is not used by default. It is the custom field filter for group members that specifies the custom fields to be obtained. For details on the custom fields of group members, see Custom Fields.
Limit Integer Optional The maximum number of members whose information to be obtained at a time. The value must be no greater than 10,000. If this field is not specified, the information of all members in the group will be obtained.
Offset Integer Optional The sequence number of the starting member whose information to be pulled. If this field is not specified, information will be obtained from the first member.

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

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 Error information.
MemberNum Integer The total number of members in the group.
MemberList Array The list of obtained group members, which contains the information of all or specified group members. For details on group member information fields, see Group Member Profiles.
AppMemberDefinedData Array Returned member custom 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.

Error Code Description
10002 An internal server error occurred. To correct it, try again.
10003 The request command word is invalid.
10004 A parameter is invalid. To correct it, check whether request parameters are correct based on the error description.
10007 The operator dose not have sufficient permissions for this operation. To correct it, check whether the operator is the app admin or whether the operator has the permission to read fields in the request.
10010 The group does not exist or has been dismissed.
10015 The group ID is invalid. To correct it, check whether the group ID is correct.
10018 The response packet length exceeds the maximum packet length (1 MB). The amount of group member data is too large. To correct it, use the Limit and Offset fields to pull group member information by page.

References

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