Help & DocumentationInstant MessagingServer APIREST APIGroup ManagementQuerying the Identity of a User in a Group

Querying the Identity of a User in a Group

Last updated: 2020-05-14 17:54:41

PDF

Contents：

Feature Description

This API is used by the app admin to obtain the roles of a batch of users in a group.

Call Description

Applicable group types

Group Type Support for This RESTful API
Private group Yes
Public group Yes
Chat Room Yes
Audio-video Chat Room No (see description below)
Online Member Broadcast Chat Room No (see description below)

IM provides the five built-in group types listed above. For more information, see Group system.

  • Audio-video chat rooms do not support the querying of roles of users in a group through this RESTful API. If you perform this operation in such groups, a 10007 error will be returned. To query the roles of users, the admin can call the [Obtaining Group Member Details](/doc/product/269/obtaining group member details) API.
  • No admin or group owner can be configured for online member broadcast groups, and all members are common members. Therefore, this RESTful API cannot be used to query the roles of users in such groups.

Example request URL

https://console.tim.qq.com/v4/group_open_http_svc/get_role_in_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The following table only describes the parameters that are modified when this API is called. For more information about other parameters, see RESTful API Overview.

Parameter Description
v4/group_open_http_svc/get_role_in_group The request API.
sdkappid The SDKAppID assigned by the IM console when an app is created.
identifier The value of this parameter must be an app admin account. For more information, see App Admin.
usersig The signature generated by the app admin account. For details on the operation, see Generating UserSig.
random A random 32-bit unsigned integer ranging from 0 to 4294967295.

Maximum call frequency

200 times/second

Example request packet

This request packet is used to obtain the list of groups that a user has joined. The group information includes the group ID and the IDs of group members whose roles are to be queried.

{
    "GroupId": "@TGS#2C5SZEAEF",
    "User_Account": [ // Up to 500 accounts are supported.
        "leckie",
        "peter",
        "wesley"
    ]
}

Request packet fields

Field Type Attribute Description
GroupId String Required ID of the group to be queried
User_Account Array Required User accounts to be queried. Up to 500 accounts are supported.

Example response packet

{
    "ActionStatus":"OK",
    "ErrorInfo":"",
    "ErrorCode": 0,
    "UserIdList": [ //Result
        {
            "Member_Account": "leckie",
            "Role": "Owner" // Role: Owner/Admin/Member/NotMember
        },
        {
            "Member_Account": "peter",
            "Role": "Member"
        },
        {
            "Member_Account": "wesley",
            "Role": "NotMember"
        }
    ]
}

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 The error information.
UserIdList Array Members’ identity information pulled from the group. The identity can be any of the following: Owner: group owner. Admin: group administrator. Member: group member. NotMember: not a group member.

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.
For public 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. Try again.
10003 The request command word is invalid.
10004 Parameters are invalid. Check whether the request is correct based on the error description.
10007 The user does not have sufficient operation permissions. For example, a common member in a public group attempts to remove a member from the group, but only the app admin has the permission to do so.
10010 The group does not exist or has been disbanded.
10015 Failed to parse the JSON format. Check whether the request packet meets JSON specifications.

Debugging Tool

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

Reference

Obtaining the list of groups that a user has joined (v4/group_open_http_svc/get_joined_group_list)