Obtain information about users in a room

Overview

You can call this operation to obtain information about users in a room by room ID, including the number of users, user ID, and username.

Request method and endpoint

Request method: GET
Request URL: https://zim-api.zego.im/?Action=QueryRoomUserList
Protocol: HTTPS
QPS limit: 20 calls per second

Request parameters

The following table describes only the operation-specific request parameters and some common request parameters. For the complete list of common request parameters, see the Common request parameters section of the Accessing Server APIs topic.

Parameter	Type	Required	Description
RoomId	String	Yes	The room ID, which cannot exceed 32 bytes in length and can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&'，'('，')'，'+'，'-'，':'，';', '<'，'='，'.'，'>', '?', '@', '[', ']', '^', '_', '{', '}', '\|', '~'.
Mode	Number	No	Specifies the order of logged-in users in a room. Valid values: `0`: chronological order, which is the default value. `1`: reverse chronological order.
NextFlag	String	No	The flag for a paginated pull. For the first pull, set this parameter to `0`. For subsequent pulls, enter the value returned from the previous pull. If `NextFlag` is `0` in the returned result, the list of all users in a room is obtained. For example, if 250 users are in a room: In the first call, set `Limit` to `100` and `NextFlag` to `0` to query the first batch of 100 users in order. In the returned result, `NextFlag` is `1`. In the second call, set `Limit` to `100` and `NextFlag` to `1` to query the second batch of 100 users in order. In the returned result, `NextFlag` is `2`. In the third call, set `Limit` to `100` and `NextFlag` to `2` to query the third batch of 50 users in order. In the returned result, `NextFlag` is `0`, indicating the query completes.
Limit	Number	No	The number of users to be queried at a time. Value range: [0, 500], that is, up to 500 users can be returned per call. If more than 500 users are in a room, call this operation multiple times and ensure that `Limit` is set to the same value per call. If the value is empty or greater than 500, `500` is used by default. If you need a higher limit, contact ZEGOCLOUD technical support.

Sample request

https://zim-api.zego.im/?Action=QueryRoomUserList
&RoomId=RoomId
&Mode=0
&NextFlag=0
&Limit=500
&<Common request parameters>

https://zim-api.zego.im/?Action=QueryRoomUserList
&RoomId=RoomId
&Mode=0
&NextFlag=0
&Limit=500
&<Common request parameters>

Response parameters

Parameter	Type	Description
Code	Number	The return code.
Message	String	The description of the request result.
RequestId	String	The request ID.
Count	Number	The number of users in the room.
NextFlag	String	The flag for a paginated pull. If this parameter is not `0`, information about more users is to be returned. In this case, set this parameter as needed to pull the remaining information. If this parameter is `0`, information of all users is returned. Aside from the explanations mentioned above, this field has no association with the list information. Please do not base any other logic on it.
UserList	Array of Object	The list of users.
└UserId	String	The user ID.
└UserName	String	The username.

Sample response

{
    "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"
        }
    ]
}

Return codes

The following table describes only the return codes related to the business logic of the operation. For the complete list of return codes, see Return codes.

Return Code	Description	Solution
660000002	Invalid parameter.	Check the input parameter.
660300001	The room does not exist.	Check whether the value of the `RoomId` parameter is valid or whether the room has been destroyed.
660300006	The QPS limit is exceeded.	This operation can be called up to 20 times per second. Try again later.
660300007	Failed to obtain the room.	Contact ZEGOCLOUD technical support.
660300008	Failed to obtain the list of users in the room, because the number of users is empty. In general, this is due to a room destruction latency.	No handling is required.