QueryRoomUserList

GET

https://zim-api.zego.im/

Obtain information about room members based on the room ID, including the number of room users, user IDs, and names.

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [QueryRoomUserList]

API prototype parameter

https://zim-api.zego.im/?Action=QueryRoomUserList

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature example for how to generate.

Timestamp int64required

💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature example for how to generate, with a maximum error of 10 minutes.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

Signature stringrequired

💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

application/json

Body

required

RoomId stringrequired

Possible values: <= 32 characters

Room ID, with a maximum length of 32 bytes. Only supports numbers, English characters, and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.

Mode number

Possible values: [0, 1]

Default value: 0

Sort by user login time to the room:

0: In chronological order (default).
1: In reverse chronological order.

NextFlag string

Pagination flag. Leave it empty for the first call, and then fill in the NextFlag value returned from the previous call. When the returned NextFlag is 0, it means the room member list has been fully retrieved.

For example, if there are 250 members in the room, when calling this API to query the room member list:

First call: Set Limit to 100, leave NextFlag empty, query users 1 to 100; the NextFlag value in the returned result is 1.
Second call: Set Limit to 100, set NextFlag to 1, query users 101 to 200; the NextFlag value in the returned result is 2.
Third call: Set Limit to 100, set NextFlag to 2, query users 201 to 250; query complete, the NextFlag in the returned result is 0.

Limit number

Possible values: >= 0 and <= 500

Number of users to query in a single call, with a value range of [0, 500]. This means calling this API once can return a maximum of 500 members.

When the number of members in the room exceeds Limit, you need to call this API multiple times and keep Limit consistent.

If left empty or greater than 500, the default value is 500.

If you need to increase the query result limit, please contact ZEGOCLOUD Technical Support for configuration.

Responses

application/json

Schema
Example (from schema)
Example

Schema

Code integer

Return code.

The following only lists the return codes related to the API business logic. For the complete return codes, please refer to Return codes.

Return code	Description	Suggested Solution
660000002	Parameter error.	Please check the request parameters.
660300001	Room does not exist.	Please check if the RoomId is correct or if the room has been destroyed.
660300006	Call frequency limit exceeded.	The call frequency is 20 times/s, please try again later.
660300007	Failed to get room.	Please contact ZEGOCLOUD Technical Support.
660300008	Failed to get room user list; the number of room users is empty, usually during the room delayed destruction period.	No action required.

Message string

Description of the request result.

RequestId string

Request ID.

Count number

Current number of users in the room.

NextFlag string

Pagination flag. If not empty, it indicates that there is still user information that has not been returned, and you need to set this field to the request parameter NextFlag to retrieve more user information; if empty, it means all user information has been returned.

Note

Apart from the above description, this field has no association with the list information. Please do not base any other logic on it.

UserList object[]

Member list.

Array[

UserId string

User ID.

UserName string

User name.

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "Count": 2,
  "NextFlag": "0",
  "UserList": [
    {
      "UserId": "aaa",
      "UserName": "UserA"
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "Count": 2,
  "NextFlag": "0",
  "UserList": [
    {
      "UserId": "aaa",
      "UserName": "UserA"
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "Count": 2,
  "NextFlag": "0",
  "UserList": [
    {
      "UserId": "aaa",
      "UserName": "UserA"
    },
    {
      "UserId": "bbb",
      "UserName": "UserB"
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "Count": 2,
  "NextFlag": "0",
  "UserList": [
    {
      "UserId": "aaa",
      "UserName": "UserA"
    },
    {
      "UserId": "bbb",
      "UserName": "UserB"
    }
  ]
}