tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Chat
    Documentation
    Download PDF

    Getting Group Member Profiles

    Last updated: 2024-02-07 17:15:28
    Download PDF

      Overview

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

      API Calling Description

      Applicable group types

      Group Type ID
      RESTful API Support
      Private
      Yes. Same as the work group (Work) in the new version.
      Public
      Yes
      ChatRoom
      Yes. Same as the meeting group (Meeting) in the new version.
      AVChatRoom
      No
      Community
      Yes. Getting group member profiles by using the Next field.
      These are the preset group types in IM. For more information, see Group System.
      Note
      Due to the large number of members in a community group, the pagination getting method is changed to the batch getting method based on the Next field.

      Sample request URL

      https://xxxxxx/v4/group_open_http_svc/get_group_member_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

      Request parameters

      The following table only describes the modified parameters when this API is called. For more information on other parameters, please see RESTful API Overview.
      Parameter
      Description
      https
      The request protocol is HTTPS, and the request method is POST.
      xxxxxx
      Domain name corresponding to the country/region where your SDKAppID is located.
      China: console.tim.qq.com
      Singapore: adminapisgp.im.qcloud.com
      Seoul: adminapikr.im.qcloud.com
      Frankfurt: adminapiger.im.qcloud.com
      India: adminapiind.im.qcloud.com
      Silicon Valley: adminapiusa.im.qcloud.com
      v4/group_open_http_svc/get_group_member_info
      Request API
      sdkappid
      SDKAppID assigned by the IM console when an app is created
      identifier
      App admin account. For more information, please see the App Admin section in Login Authentication.
      usersig
      Signature generated in the app admin account. For details on how to generate the signature, please see Generating UserSig.
      random
      A random 32-bit unsigned integer ranging from 0 to 4294967295
      contenttype
      Request format, which should always be json.

      Maximum call frequency

      200 calls per second

      Sample request

      Basic format A basic request is used to obtain detailed group member information, including group member profiles and custom group member fields. The request requires 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. Maximum value: 200; recommended value: 100
      Offset: specifies from which group member to start pulling information. If the page number starts from 1, the value of Offset for each page should be (page number – 1) × number of group members to display on each page. For example, to display 20 group members on each page, the request parameters for the first page should be {"Limit": 20, "Offset": 0}, the request parameters 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 to pull information
          "Offset": 0 // Sequence number of the member from whom to start pulling information
      }
      Caution
      The community currently does not support paging to get the group member details.
      Batch You can use the Limit and Next fields to control the batch mode:
      Limit: specifies the maximum number of members in the MemberList array in the response. Maximum value: 100
      Next: specifies a member position from which subsequent information is to be pulled. For the first request, the client request parameter Next must pass in "". For the last request, the server returns "" for the Next parameter, indicating that the information pulling ends. For intermediate requests, the client request parameter Next uses the last value of Next returned by the server. This is similar to Redis scan cursor queries.
      For example, if you are to perform batch pulling, the parameters in the first request should be {"Limit" : 20, "Next" : ""}, and the server returns the following: 
      {
         "ActionStatus": "OK",
         "ErrorInfo": "",
         "ErrorCode": 0,
         "Next": "144115265295492787",
         "MemberList": [
                 ....
      The parameters in the second request should be {"Limit" : 20, "Next" : "144115265295492787"}. And so on, until the server replies with Next as "", indicating that there is no subsequent member information, and the client should end the query.
      {
          "GroupId":"@TGS#_@TGS#cAVQXXXXXX", // Group ID (required)
          "Limit": 100, // Maximum number of members to pull information
          "Next": "" // Start pulling from the position where the last pulling ends
      }
      Caution
      Only the community supports obtaining group member details in batches.
      Specifying information to pull You can use the MemberInfoFilter filter field to specify fields to pull. Fields that are not specified in it will not be pulled.
      {
        "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
        "MemberInfoFilter": [ // Information to pull, 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",
            "MuteUntil",
            "NameCard"
        ]
      }
      Pulling the information of members in the specified role You can use the MemberRoleFilter filter field to specify the role of members to pull information. 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"
        ]
      }
      Pulling custom group member fields You can use the AppDefinedDataFilter_GroupMember filter field to specify the custom group member fields to pull. Fields that are not specified in it will not be pulled.
      {
        "GroupId":"@TGS#37AB3PAEC", // Group ID (required)
        "AppDefinedDataFilter_GroupMember": [ // Filter for custom group member fields
            "MemberDefined2" // Key of a custom group member field
        ]
      }
      Response to an ALL IN ONE request
      {
        "GroupId":"@TGS#1NVTZEAE4", // Group ID (required)
        "MemberInfoFilter": [ // Information to pull. If this field is not specified, all group member information will be pulled.
            "Role",
            "JoinTime",
            "MsgSeq",
            "MsgFlag",
            "LastSendMsgTime",
            "MuteUntil",
            "NameCard"
        ],
       "MemberRoleFilter":[ // Member role filter
            "Owner",
            "Member"
        ],
       "AppDefinedDataFilter_GroupMember": [ // Filter for custom group member fields
            "MemberDefined2", // Key of a custom group member field
            "MemberDefined1"
        ],
        "Limit": 100, // Maximum number of members to pull information
        "Offset": 0 // Sequence number of the member from whom to start pulling information
      }

      Request fields

      Field
      Type
      Required
      Description
      GroupId
      String
      Yes
      ID of the group to pull member information
      MemberInfoFilter
      Array
      No
      Information to pull. If this field is not specified, all group member information will be pulled. For details on group member information fields, see Group member profile.
      MemberRoleFilter
      Array
      No
      Role of group members to pull information. 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
      No
      This field is omitted by default. It specifies the custom group member fields to pull. For more information, see the Custom Fields section in Group System.
      Limit
      Integer
      No
      Maximum number of members to pull information at a time. The value cannot exceed 6000. If this field is not specified, the information of all members in the group will be obtained.
      Offset
      Integer
      No
      Sequence number of the member from whom to start pulling information. If this field is set to 0, the information is pulled starting from the first member.
      Next
      String
      No
      Position of the last member pulled. This field is required for a community group. A community group does not support the Offset field. It uses the Next field instead. For the first call, "" must be passed in for Next. For subsequent calls, the last value of Next must be passed in.

      Sample response

      Response to a basic or pagination request
      {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "Next": "144115265295492787", // This field is returned only for a community group
        "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 when the member sent a message
                "MuteUntil": 1431069882, // Muting end time in seconds
                "AppMemberDefinedData": [ // Custom group member fields
                    {
                       "Key": "MemberDefined1",
                       "Value": "ModifyDefined1"
                    },
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            },
            {
                "Member_Account": "peter",
                "Role": "Member ",
                "JoinTime": 1425976500,
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500,
                "MuteUntil": 0, // `0`: the member is not muted; other values: the time when the member will be unmuted
                "AppMemberDefinedData": [ // Custom group member fields
                    {
                       "Key": "MemberDefined1",
                       "Value": "ModifyDefined1"
                    },
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            }
        ]
      }
      Response to a request 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, // Time when the member joined the group
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500, // Last time when the member sent a message
                "MuteUntil": 1431069882, // Muting end time in seconds
            },
            {
                "Member_Account": "peter",
                "Role": "Member ",
                "JoinTime": 1425976500,
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500,
                "MuteUntil": 0, // `0`: the member is not muted; other values: the time when the member will be unmuted
            }
        ]
      }
      Pulling the information of members in the specified role
      {
        "ActionStatus": "OK", // The request succeeded.
        "ErrorCode": 0, // Return code
        "MemberList": [
            {
                "JoinTime": 1450680436, // Time when the member joined the group
                "LastSendMsgTime": 0, // Last time when the member sent a message
                "Member_Account": "Test_1", // Member account
                "MsgFlag": "AcceptNotNotify", // Type of member messages being blocked
                "MsgSeq": 1, // Sequence number of the member’s read message
                "NameCard": "", // Member’s contact card
                "Role": "Owner", // Member’s role
                "MuteUntil": 0 // `0`: the member is not muted; other values: the time when the member will be unmuted
            },
            {
                "JoinTime": 1450680436,
                "LastSendMsgTime": 0,
                "Member_Account": "Test_6",
                "MsgFlag": "AcceptNotNotify",
                "MsgSeq": 1,
                "NameCard": "",
                "Role": "Admin",
                "MuteUntil": 0
            }
        ],
        "MemberNum": 8 // Total number of members in the group
      }
      Pulling custom group member 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 when the member sent a message
                "MuteUntil": 1431069882, // Muting end time in seconds
                 "AppMemberDefinedData": [ // Custom group member fields
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            },
            {
                "Member_Account": "peter",
                "Role": "Member",
                "JoinTime": 1425976500,
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500,
                "MuteUntil": 0, // `0`: the member is not muted; other values: the time when the member will be unmuted
                "AppMemberDefinedData": [ // Custom group member fields
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            }
        ]
      }
      Response to an ALL IN ONE request
      {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "Next": "144115265295492787", // This field is returned only for a community group
        "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 when the member sent a message
                "MuteUntil": 1431069882, // Muting end time in seconds
                "AppMemberDefinedData":[ // Custom group member fields
                    {
                       "Key":"MemberDefined1",
                       "Value":"ModifyDefined1"
                    },
                    {
                        "Key":"MemberDefined2",
                        "Value":"ModifyDefined2"
                    }
                 ]
            },
            {
                "Member_Account": "peter",
                "Role": "Member",
                "JoinTime": 1425976500,
                "MsgSeq": 1233,
                "MsgFlag": "AcceptAndNotify",
                "LastSendMsgTime": 1425976500,
                "MuteUntil": 0, // `0`: the member is not muted; other values: the time when the member will be unmuted
                "AppMemberDefinedData": [ // Custom group member fields
                    {
                       "Key": "MemberDefined1",
                       "Value": "ModifyDefined1"
                    },
                    {
                        "Key": "MemberDefined2",
                        "Value": "ModifyDefined2"
                    }
                 ]
            }
        ]
      }

      Response fields

      Field
      Type
      Description
      ActionStatus
      String
      Request result. OK: successful; FAIL: failed
      ErrorCode
      Integer
      Error code. 0: successful; other values: failed
      ErrorInfo
      String
      Error information
      MemberNum
      Integer
      Total number of members in the group
      MemberList
      Array
      Returned group member list, which contains information of all or specified group members. For details on group member information fields, see Group member profile.
      AppMemberDefinedData
      Array
      Returned custom group member fields
      Next
      String
      Value of Next to be passed in in the next request. This field is returned only for a community group.

      Error Codes

      The returned HTTP status code for this API is always 200 unless a network error (such as error 502) occurs. The specific error code and details can be found in the response fields ErrorCode and ErrorInfo respectively. For public error codes (60000 to 79999), please see Error Codes. The following table describes the error codes specific to this API:
      Error Code
      Description
      10002
      Internal server error. Try again.
      10003
      Invalid command word.
      10004
      Invalid parameter. Check the error description and troubleshoot the issue.
      10007
      No operation permissions. Check whether the operator is an app admin or whether the operator has the permission to read the fields in the request.
      10010
      The group does not exist or has been deleted.
      10015
      Invalid group ID. Use the correct group ID.
      10018
      The response exceeds the maximum size allowed (1 MB) because the group member data volume is too large. Try to use Limit and Offset to pull the group member data by page.

      API Debugging Tool

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

      References

      Modifying the Profile of a Group Member (v4/group_open_http_svc/modify_group_member_info)
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy