Obtaining Permission Group Member List

Recent Pages

Obtaining Permission Group Member List

Last updated: 2024-07-16 11:20:06

Feature Overview
 App admins can call this API to obtain group member information based on the group ID.
API Calling Description
Applicable Group Types
Group Type ID
Whether This RESTful API Is Supported
Private
Not supported, same as Work (Work Friend Group) in the new version
Public
Not supported
ChatRoom
Not supported, same as Meeting (Temporary Meeting Group) in the new version
AVChatRoom
Not supported
Community
Supported
Chat provides the aforementioned group types. For details, refer to Group System.
Sample Request URL
https://xxxxxx/v4/group_open_http_svc/get_permission_group_member_list?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
Request Parameters
The table below only lists the parameters modified when calling this API and their descriptions. For details on the parameters, refer to RESTful API Overview.
Parameter
Description
xxxxxx
The dedicated domain name for 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
Silicon Valley: adminapiusa.im.qcloud.com
Jakarta: adminapiidn.im.qcloud.com
v4/group_open_http_svc/get_permission_group_member_list
Request API
sdkappid
SDKAppID assigned by the Chat console when an app is created
identifier
You must be an app admin account. For details, refer to App Admins.
usersig
The signature generated by the app admin account. For details, refer to Generating UserSig.
random
A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype
Request format fixed value: json
Maximum Calling Frequency
200 queries/sec.
Sample Request Packet
Basic Form
It is used to obtain detailed information of permission group members (including group member information and group member dimensions from the Definition field). The request only contains the group ID and permission group ID.
{
  "GroupId": "@TGS#_@TGS#cAVQXXXXXX", // Group ID (required)
  "PermissionGroupId":"@PMG#_@PMG#cDR",// Permission group ID (required)
}
Batch Acquisition
Use Limit and Next values to control pagination retrieval:
Limit restricts the number of members in the MemberList array in the response packet, which cannot exceed 50.
Next controls the retrieval of subsequent information from a certain member's position. In the first request, the client's request parameter for Next shall be ""; when the server's return for Next is "" after the last request, it indicates the end of retrieval.
For requests in between, the client's Next shall use the Next returned by the server from the previous request. It is similar to the scan cursor query of Redis.
 For example: Suppose you need to batch pull, the request parameters for the first time shall be:{"Limit": 20, "Next": ""}, and the server returns the following content.
{
   "ActionStatus": "OK",
   "ErrorInfo": "",
   "ErrorCode": 0,
   "Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1",
   "MemberList": [
           ....
 The request parameters for the second time shall be {"Limit": 20, "Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1"}.
And so on, until the server's response packet returns Next as "", indicating there is no subsequent member information, and the client shall end the query.
{
    "GroupId":"@TGS#_@TGS#cAVQXXXXXX", // Group ID (required)
    "PermissionGroupId":"@PMG#_@PMG#cDR",// Permission group ID (required)
    "Limit": 50, // The maximum number of members whose information to be obtained
    "Next": "" // Start pulling from the end of the last pull
}
Specifying the Information to Be Pulled
Select the fields to be pulled through the MemberInfoFilter filter. Fields not specified in the filter will not be pulled.
{
  "GroupId":"@TGS#_@TGS#cAVQXXXXXX", // Group ID (required)
  "PermissionGroupId":"@PMG#_@PMG#cDR",// Permission group ID (required)
  "MemberInfoFilter": [ // Which information is needed (Member_Account is included by default). If this field is not specified, then information of all members is included.
      "Role",
      "JoinTime",
      "MsgSeq",
      "MsgFlag",
      "LastSendMsgTime",
      "JoinPermissionGroupTime",
      "MuteUntil",
      "NameCard"
  ]
}
Pulling Custom Field for Group Members
Select the custom field for group member to be pulled through the AppDefinedDataFilter_GroupMember filter. Fields not specified in the filter will not be pulled.
{
  "GroupId":"@TGS#_@TGS#cAVQXXXXXX", // Group ID (required)
  "PermissionGroupId":"@PMG#_@PMG#cDR",// Permission group ID (required)
  "AppDefinedDataFilter_GroupMember": [ // Filter for custom field of group members
      "MemberDefined2" // Key of the custom field for group members
  ]
}
ALL IN ONE
{
  "GroupId":"@TGS#_@TGS#cAVQXXXXXX", // Group ID (required)
  "PermissionGroupId":"@PMG#_@PMG#cDR",// Permission group ID (required)
  "MemberInfoFilter": [ // Which information is needed. If this field is not specified, then information of all members is included.
      "Role",
      "JoinTime",
      "JoinPermissionGroupTime",
      "MsgSeq",
      "MsgFlag",
      "LastSendMsgTime",
      "MuteUntil",
      "NameCard"
  ],
 "AppDefinedDataFilter_GroupMember": [ // Filter for custom field of group members
      "MemberDefined2", // Key of the custom field for group members
      "MemberDefined1"
  ],
  "Limit": 50, // The maximum number of members whose information to be obtained
  "Offset": 0 // The starting point to obtain member information
}
Description of Request Packet Fields
Field
Type
Attribute
Description
GroupId
String
Required
ID of the group from which member information needs to be obtained
PermissionGroupId
String
Required
ID of the permission group to operate on
MemberInfoFilter
Array
Optional
Which information is needed. If this field is not specified, then information of all members is included. For details on member information fields, refer to Group Member Information.
AppDefinedDataFilter_GroupMember
Array
Optional
By default, this is not available. This field is used as a filter for custom fields in the group member dimension, specifying the custom fields of the group member dimension that need to be obtained For details, refer to Custom Fields.
Next
String
Optional
The member location obtained last time. It is required for communities, as communities do not support the Offset parameter. Use the Next parameter instead. Fill in "" for the first call, and use the Next value returned for subsequent retrievals.
Sample response packets
Basic Form and Pagination Retrieval
{
  "ActionStatus": "OK",
  "ErrorInfo": "",
  "ErrorCode": 0,
  "Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1",
  "MemberNum": 2, // Total number of members in this permission group
  "MemberList": [ // Permission group member list
      {
          "Member_Account": "bob",
          "Role": "Owner",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500, // Last message sent time
          "MuteUntil": 1431069882, // Mute until (seconds)
          "AppMemberDefinedData": [ // Group member's custom definition field
              {
                 "Key": "MemberDefined1",
                 "Value": "ModifyDefined1"
              },
              {
                  "Key": "MemberDefined2",
                  "Value": "ModifyDefined2"
              }
           ]
      },
      {
          "Member_Account": "peter",
          "Role": "Member ",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500,
          "MuteUntil": 0, // 0 indicates not muted; otherwise, it's the mute expiry timestamp.
          "AppMemberDefinedData": [ // Group member's custom definition field
              {
                 "Key": "MemberDefined1",
                 "Value": "ModifyDefined1"
              },
              {
                  "Key": "MemberDefined2",
                  "Value": "ModifyDefined2"
              }
           ]
      }
  ]
}
Pulling Specified Fields
{
  "ActionStatus": "OK",
  "ErrorInfo": "",
  "ErrorCode": 0,
  "Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1",
  "MemberNum": 2, // Total number of members in this permission group
  "MemberList": [ // Permission group member list
      {
          "Member_Account": "bob",
          "Role": "Owner",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500, // Last message sent time
          "MuteUntil": 1431069882, // Mute until (seconds)
      },
      {
          "Member_Account": "peter",
          "Role": "Member ",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500,
          "MuteUntil": 0, // 0 indicates not muted; otherwise, it's the mute expiry timestamp.
      }
  ]
}
Pulling Custom Field for Group Members
{
  "ActionStatus": "OK",
  "ErrorInfo": "",
  "ErrorCode": 0,
  "Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1",
  "MemberNum": 2, // Total number of members in this permission group
  "MemberList": [ // Permission group member list
      {
          "Member_Account": "bob",
          "Role": "Owner",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500, // Last message sent time
          "MuteUntil": 1431069882, // Mute until (seconds)
           "AppMemberDefinedData": [ // Custom fields for group members
              {
                  "Key": "MemberDefined2",
                  "Value": "ModifyDefined2"
              }
           ]
      },
      {
          "Member_Account": "peter",
          "Role": "Member",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500,
          "MuteUntil": 0, // 0 indicates not muted; otherwise, it's the mute expiry timestamp.
          "AppMemberDefinedData": [ // Group member's custom definition field
              {
                  "Key": "MemberDefined2",
                  "Value": "ModifyDefined2"
              }
           ]
      }
  ]
}
ALL IN ONE
{
  "ActionStatus": "OK",
  "ErrorInfo": "",
  "ErrorCode": 0,
  "Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1",
  "MemberNum": 2, // Total number of members in this permission group
  "MemberList": [ // Permission group member list
      {
          "Member_Account": "bob",
          "Role": "Owner",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500, // Last message sent time
          "MuteUntil": 1431069882, // Mute until (seconds)
          "AppMemberDefinedData":[ // Custom fields for group members
              {
                 "Key":"MemberDefined1",
                 "Value":"ModifyDefined1"
              },
              {
                  "Key":"MemberDefined2",
                  "Value":"ModifyDefined2"
              }
           ]
      },
      {
          "Member_Account": "peter",
          "Role": "Member",
          "JoinTime": 1425976500, // Join time
          "JoinPermissionGroupTime": 1704804868, // Time joined the permission group
          "MsgSeq": 1233,
          "MsgFlag": "AcceptAndNotify",
          "LastSendMsgTime": 1425976500,
          "MuteUntil": 0, // 0 indicates not muted; otherwise, it's the mute expiry timestamp.
          "AppMemberDefinedData": [ // Group member's custom definition field
              {
                 "Key": "MemberDefined1",
                 "Value": "ModifyDefined1"
              },
              {
                  "Key": "MemberDefined2",
                  "Value": "ModifyDefined2"
              }
           ]
      }
  ]
}
Description of Response Packet Fields
Field
Type
Description
ActionStatus
String
Result of the request processing:
OK: Indicates successful processing.
FAIL: Indicates failure.
ErrorCode
Integer
Error code
0: Indicates success.
Non-zero: Indicates failure.
ErrorInfo
String
Error message
MemberNum
Integer
Total number of members in this permission group
MemberList
Array
Obtained permission group members list, which includes all or specified group member information. For details on member information fields, refer to Group Member Information.
AppMemberDefinedData
Array
Returned group member custom field information
Next
String
Next value that shall be passed in the next request
Error Codes
Unless a network error (such as a 502 error) occurs, the HTTP return code for this API is always 200. The real error code and error message are indicated by ErrorCode and ErrorInfo in the response packet body.
Common error codes (60000 to 79999) can be found in the Error Codes document.
The private error codes for this API are as follows:
Error Code
Description
10002
Internal server error. Try again.
10003
Illegal request command word
10004
Invalid parameter. Check if the request is correct based on the error description.
10007
Insufficient operation permissions. Confirm whether the operator is an app admin or has permission to read the fields in the request.
10010
The group does not exist, or it existed in the past but has now been dissolved.
10015
Invalid group ID. Check if the group ID is filled in correctly.
110006
The permission group does not exist, or it existed in the past but has now been dissolved.
110008
Invalid permission group ID. Check if the permission group ID is filled in correctly.
API Debugging Tool
Use the RESTful API Online Debugging Tool to debug this API.
﻿

Contact Us

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

Technical Support

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

7x24 Phone Support

tencent cloud

Recent Pages

Obtaining Permission Group Member List

Feature Overview

API Calling Description

Applicable Group Types

Sample Request URL

Request Parameters

Maximum Calling Frequency

Sample Request Packet

Description of Request Packet Fields

Sample response packets

Description of Response Packet Fields

Error Codes

API Debugging Tool

Was this page helpful?

Was this page helpful?

Group Type ID	Whether This RESTful API Is Supported
Private	Not supported, same as Work (Work Friend Group) in the new version
Public	Not supported
ChatRoom	Not supported, same as Meeting (Temporary Meeting Group) in the new version
AVChatRoom	Not supported
Community	Supported

Parameter	Description
xxxxxx	The dedicated domain name for 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` Silicon Valley: `adminapiusa.im.qcloud.com` Jakarta: `adminapiidn.im.qcloud.com`
v4/group_open_http_svc/get_permission_group_member_list	Request API
sdkappid	SDKAppID assigned by the Chat console when an app is created
identifier	You must be an app admin account. For details, refer to App Admins.
usersig	The signature generated by the app admin account. For details, refer to Generating UserSig.
random	A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype	Request format fixed value: `json`

Field	Type	Attribute	Description
GroupId	String	Required	ID of the group from which member information needs to be obtained
PermissionGroupId	String	Required	ID of the permission group to operate on
MemberInfoFilter	Array	Optional	Which information is needed. If this field is not specified, then information of all members is included. For details on member information fields, refer to Group Member Information.
AppDefinedDataFilter_GroupMember	Array	Optional	By default, this is not available. This field is used as a filter for custom fields in the group member dimension, specifying the custom fields of the group member dimension that need to be obtained For details, refer to Custom Fields.
Next	String	Optional	The member location obtained last time. It is required for communities, as communities do not support the Offset parameter. Use the Next parameter instead. Fill in "" for the first call, and use the Next value returned for subsequent retrievals.

Error Code	Description
10002	Internal server error. Try again.
10003	Illegal request command word
10004	Invalid parameter. Check if the request is correct based on the error description.
10007	Insufficient operation permissions. Confirm whether the operator is an app admin or has permission to read the fields in the request.
10010	The group does not exist, or it existed in the past but has now been dissolved.
10015	Invalid group ID. Check if the group ID is filled in correctly.
110006	The permission group does not exist, or it existed in the past but has now been dissolved.
110008	Invalid permission group ID. Check if the permission group ID is filled in correctly.

tencent cloud

Sign Up

Log in

Recent Pages

Obtaining Permission Group Member List

Feature Overview

API Calling Description

Applicable Group Types

Sample Request URL

Request Parameters

Maximum Calling Frequency

Sample Request Packet

Description of Request Packet Fields

Sample response packets

Description of Response Packet Fields

Error Codes

API Debugging Tool

Was this page helpful?

Was this page helpful?