Obtaining Group Member Profiles

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

    Feature Description

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

    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.
    Public Yes.
    ChatRoom Yes. Same as Meeting (temporary meeting group) in the new version.
    AVChatRoom Yes, but the maximum number of members cannot exceed 300.

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

    Due to differences in scenario implementation, for a livestreaming group (AVChatRoom group), you can only obtain the group member profiles of the first 300 members. The profiles of members who join the group after the 300 threshold is reached cannot be obtained.

    Sample request URL

    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 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_group_member_info 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, 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
      A request in basic form is used to obtain detailed group member information, including group member profiles and custom fields specific to group members. The request contains only the group ID.
      {
        "GroupId":"@TGS#1NVTZEAE4"  // Group ID (required)
      }
    • Pagination
      You can use the Limit and Offset fields to control the pagination mode:
      • Limit specifies the maximum number of members in the MemberList array in the response packet, which cannot exceed 6,000.
      • Offset specifies the sequence number of the group member starting from which the information is pulled. If pagination is requested (the page number starts from 1), the Offset value of each page should be (Page number – 1) × Number of group members displayed on each page.
        For example, if pagination is requested and 20 group members 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.
    {
        "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
        "Limit": 100, // Maximum number of members whose information is pulled
        "Offset": 0 // Sequence number of the group member starting from which the information is pulled
    }
    • Specify information to be pulled
      You can use the MemberInfoFilter field to specify fields to pull. Fields not specified in MemberInfoFilter will not be pulled.
      {
        "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
        "MemberInfoFilter": [ // Specify 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"
        ]
      }
    • Pull the information of members in the specified role
      You can use the MemberRoleFilter field to specify the role of members whose information is to be pulled. If this field is not specified, the information of members in all roles will be pulled.
      {
        "GroupId":"@TGS#37AB3PAEC", // Group ID (required)
        "MemberRoleFilter":[ // Member role filter
            "Owner",
            "Member"
        ]
      }
    • Pull group member custom fields
      You can use the AppDefinedDataFilter_GroupMember field to specify the custom fields of group members to pull. Fields that are not specified by AppDefinedDataFilter_GroupMember will not be pulled.
      {
        "GroupId":"@TGS#37AB3PAEC", // Group ID (required)
        "AppDefinedDataFilter_GroupMember": [ // Filter for group member custom fields
            "MemberDefined2" // Key of the group member custom field
        ]
      }
    • ALL IN ONE
      {
        "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
        "MemberInfoFilter": [ // Specify the information to obtain. 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": [ // Filter for group member custom fields
            "MemberDefined2" // Key of the group member custom field
            "MemberDefined1"
        ],
        "Limit": 100, // Maximum number of members whose information is pulled
        "Offset": 0 // Sequence number of the group member starting from which the information is pulled
      }

    Request packet fields

    Field Type Property Description
    GroupId String Required ID of the group, for which member information needs to be obtained
    MemberInfoFilter Array Optional 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 Role of group members whose information will be pulled. If this field is not specified, the information of members in all roles will be pulled. The member role can be "Owner", “Admin", or "Member".
    AppDefinedDataFilter_GroupMember Array Optional This field is omitted by default. It is the member custom field filter that specifies the member custom fields that need to be obtained. For details on custom fields specific to group members, see Custom Fields.
    Limit Integer Optional Number of members for whom to obtain information at a time. The value cannot exceed 10,000. If this field is not specified, the information of all members in the group will be obtained.
    Offset Integer Optional Sequence number of the member starting from which the information is pulled. If this field is not specified, the information is pulled starting from the first member.

    Sample response packet body

    • Basic form and pagination
      {
        "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, // Time when the member joined the group
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500, // Last time the member sent a message
                "ShutUpUntil": 1431069882, // Expiration time of muting (in seconds)
                "AppMemberDefinedData": [ // Group 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 value 0 indicates that the member is not muted and other values indicate the expiration time of muting.
                "AppMemberDefinedData": [ // Group member custom fields
                    {
                       "Key": "MemberDefined1",
                       "Value": "ModifyDefined1"
                    },
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            }
        ]
      }
    • Pull 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, // Time when the member joined the group
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500, // Last time the member sent a message
                "ShutUpUntil": 1431069882, // Expiration time of muting (in seconds)
            },
            {
                "Member_Account": "peter",
                "Role": "Member ",
                "JoinTime": 1425976500,
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500,
                "ShutUpUntil": 0, // The value 0 indicates that the member is not muted and other values indicate the expiration time of muting.
            }
        ]
      }
    • Pull the information of members in the specified role
      {
        "ActionStatus": "OK", // Returned successfully
        "ErrorCode": 0, // Return code
        "MemberList": [
            {
                "JoinTime": 1450680436, // Time when the member joined the group
                "LastSendMsgTime": 0, // Time when the member last sent a message
                "Member_Account": "Test_1", // Member account
                "MsgFlag": "AcceptNotNotify", // Type of the 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 value 0 indicates that the member is not muted and other values indicate the expiration time of muting.
            },
            {
                "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
      }
    • Pull group member custom 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, // Time when the member joined the group
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500, // Last time the member sent a message
                "ShutUpUntil": 1431069882, // Expiration time of muting (in seconds)
                 "AppMemberDefinedData": [ // Group member custom fields
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            },
            {
                "Member_Account": "peter",
                "Role": "Member",
                "JoinTime": 1425976500,
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500,
                "ShutUpUntil": 0, // The value 0 indicates that the member is not muted and other values indicate the expiration time of muting.
                "AppMemberDefinedData": [ // Group member custom fields
                    {
                        "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, // Time when the member joined the group
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500, // Last time the member sent a message
                "ShutUpUntil": 1431069882, // Expiration time of muting (in seconds)
                "AppMemberDefinedData":[ // Group 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 value 0 indicates that the member is not muted and other values indicate the expiration time of muting.
                "AppMemberDefinedData": [ // Group member custom fields
                    {
                       "Key": "MemberDefined1",
                       "Value": "ModifyDefined1"
                    },
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            }
        ]
      }

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

    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 An internal server error occurred. Please try again.
    10003 The request command word is invalid.
    10004 A parameter is invalid. Check the error description and troubleshoot the issue.
    10007 The operator does not have sufficient permissions for this operation. Check whether the operator is the app admin or has the permission to read the fields in the request.
    10010 The group does not exist, or once existed but has been disbanded.
    10015 The group ID is invalid. Be sure to use the correct group ID.
    10018 The response packet length exceeds the maximum packet length (1 MB) because the amount of group member data is too large. Try to use Limit and Offset to pull the group member data by page.

    API Debugging Tool

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

    Reference

    Modifying group member profiles (v4/group_open_http_svc/modify_group_member_info)

    Was this page helpful?

    Was this page helpful?

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