文档中心
即时通讯
服务端 API
房间相关
获取房间成员信息

获取房间成员信息

更新时间：2023-12-19 16:05

描述

根据房间 ID 获取房间成员的信息，包括房间用户数量、用户 ID 及名称。

接口原型

请求方法：GET
请求地址：https://zim-api.zego.im/?Action=QueryRoomUserList
传输协议：HTTPS
调用频率限制：20 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
RoomId	String	是	房间ID，长度上限为 32 字节，仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，'{'，'}'，'\|'，'~'。
Mode	Number	否	按用户登录房间时间排序： 0：按时间顺序（默认值）。 1：按时间倒序。
NextFlag	String	否	分页拉取标志，第一次填空，之后填上一次返回的 NextFlag 值。当返回的 NextFlag 为 0 时，代表房间成员列表获取完毕。例如，房间内有 250 个成员，调用本接口查询房间成员列表时：第一次调用本接口，Limit 填 100，NextFlag 传空，查询第 1 ～ 100 名用户；返回结果中的 NextFlag 值为 1。第二次调用本接口，Limit 填 100，NextFlag 填 1，查询第 101 ～ 200 名用户；返回结果中 NextFlag 值为 2。第三次调用本接口，Limit 填 100，NextFlag 填 2，查询第 201 ～ 250 名用户；查询完毕，返回结果中的 NextFlag 为 0。
Limit	Number	否	单次查询用户的数量，取值范围为 [0, 500]，即调用本接口一次最多返回 500 个成员。当房间内成员超过 Limit 时，需调用多次本接口且 Limit 需保持一致。如果传空或大于 500，则默认取值为 500。如需提高查询结果上限，请联系 ZEGO 技术支持进行配置。

请求示例

https://zim-api.zego.im/?Action=QueryRoomUserList
&RoomId=RoomId
&Mode=0
&NextFlag=0
&Limit=500
&<公共请求参数>

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
Count	Number	当前房间用户数。
NextFlag	String	分页拉取标志，非空表示还有用户的信息未返回，需要将该字段设置到请求参数 NextFlag 中拉取更多用户的信息；为空表示已经返回所有用户的信息。
UserList	Array of Object	成员列表。
UserId	String	用户 ID。
UserName	String	用户名称。

响应示例

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

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000002	参数错误。	请检查请求参数。
660300001	房间不存在。	请检查 RoomId 是否正确或房间是否已被销毁。
660300006	超出调用频率限制。	调用频率为 20 次/秒，请稍后重试。
660300007	获取房间失败。	请联系 ZEGO 技术支持。
660300008	获取房间用户列表失败；房间人数为空，一般是处于房间延迟销毁期间。	无需操作。