You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/服务端 OpenAPI 参考/房间管理/获取实时用户列表 GetRoomOnlineUsers
获取实时用户列表 GetRoomOnlineUsers
最近更新时间：2025.06.06 11:29:16首次发布时间：2024.01.03 20:25:19
我的收藏
有用
有用
无用
无用

本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。

通过指定 AppId 和房间 ID，你查询到房间中用户信息，包括存在的用户总数、不可见用户总数、用户终端设备类型等。

注意事项

  • 请求频率：当请求参数 Property 为 false 时，QPS 不得超过 40；当请求参数 Property 为 true 时，QPS 不得超过 1。
  • 可查询信息跟请求参数 Property 的取值和客户端 SDK版本有关，具体请参见返回参数。

请求说明

  • 请求方式：GET
  • 请求地址：https://rtc.volcengineapi.com?Action=GetRoomOnlineUsers&Version=2023-11-01

调试

API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数
类型
是否必选
示例值
描述
Action
String
是
GetRoomOnlineUsers
接口名称。当前 API 的名称为 GetRoomOnlineUsers。
Version
String
是
2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
AppId
String
是
661e****543cf
你的音视频应用的唯一标志。如何获取 AppId?
RoomId
String
是
Your_RoomId
要查询的房间 ID，仅支持传入 1 个。
Property
Boolean
否
false

是否要获取用户详细信息：

  • false（默认值）：否，仅获取用户 ID。
  • true：是，除用户 ID 以外，还会获取设备类型、SDK 类型等信息。
RoleType
Integer
否
0

注意

该字段仅当 Property 为 true 时才生效。

筛选要查询用户的类型。可取值如下：

  • 0（默认值）：不区分类型，返回可见用户和不可见用户。

    可返回的可见用户和不可见用户数之和上限为 200 名，若用户总数超过上限，优先返回可见用户。

  • 1：仅返回可见用户。
  • 2：仅返回不可见用户。

返回参数

下表仅列出本接口特有的返回参数，公共返回参数请参见返回结构。请求参数 Property 的取值不同，返回也不同。

请求参数 Property 为 flase

当请求参数 Property 的值设为 flase 时，返回如下：

参数类型示例值描述

RoomExists

Boolean

true

查询的房间是否存在。

  • true：存在。
  • false：不存在。

当 RoomExists 的值为 false 时，不会返回其他字段。

TotalUserInteger2查询到的用户总数。
TotalInvisibleUserInteger1查询到的不可见用户总数。不可见用户最多返回 10000 名。
VisibleUserListString[]["normal_user_1"]可见用户列表。
InvisibleUserListString[]["silent_user_1"]不可见用户列表，最多返回 10000 名。

请求参数 Property 为 true

当请求参数 Property 的值设为 true 时，返回如下表所示：

参数
类型
示例值
描述
RoomExists
Boolean
true

所查询的房间是否存在：

  • true：存在。
  • false：不存在。
当 RoomExists 的值为 false 时，不会返回其他字段。
VisibleUserList
Object[]
["user1","user2"]

可见用户列表。

注意

可返回的可见用户和不可见用户总数上限为 200 名，若用户总数超过上限，优先返回可见用户。

UserId
String
user1
用户 ID。
DeviceType
String
ios

用户终端设备的操作系统类型：

  • android
  • ios
  • mac
  • windows
  • linux
  • harmony
  • web
PlatformType
Integer
1

SDK 类型：

  • 1：Native
  • 2：Web
  • 4：抖音小程序

注意

仅当 SDK 客户端为 Native 端，且为以下版本时才返回该字段：
  • 3.60.x：3.60.8.1750 及以上。
  • 3.61.x：3.61.5 及以上版本。
  • 3.63.0 及以上版本。
MediaProcessingType
Integer
21

后端处理业务类型。

注意

仅当用户为后端处理机器人时，才会返回该字段。

取值如下：

  • 11：本地服务端录制
  • 21：单流云端录制
  • 22：合流云端录制
  • 23：合流转推
  • 24：单流转推
  • 25：在线媒体流
  • 27：云录屏
  • 28：视频抽帧
  • 29：音频切片
  • 31：转推 WTN
  • 32：语音识别和翻译服务
  • 34：AIGC Gateway
  • 35：AIGC ToB 一站式
InvisibleUserList
Object[]
["silent_user_1"]

不可见用户列表。

注意

可返回的可见用户和不可见用户数之和上限为 200 名，若用户总数超过上限，优先返回可见用户。

UserId
String
user1
用户 ID。
DeviceType
String
android

用户终端设备的操作系统类型：

  • android
  • ios
  • mac
  • windows
  • linux
  • harmony
  • web
PlatformType
Integer
Web

SDK 类型：

  • 1：Native
  • 2：Web
  • 4：抖音小程序

注意

仅当 SDK 客户端为 Native 端，且为以下版本时才返回该字段：
  • 3.60.x：3.60.8.1750 及以上。
  • 3.61.x：3.61.5 及以上版本。
  • 3.63.0 及以上版本。
MediaProcessingType
Integer
21

后端处理的业务类型。

注意

仅当用户为后端处理机器人时，才会返回该字段。

取值如下：

  • 11：本地服务端录制
  • 21：单流云端录制
  • 22：合流云端录制
  • 23：合流转推
  • 24：单流转推
  • 25：在线媒体流
  • 27：云录屏
  • 28：视频抽帧
  • 29：音频切片
  • 31：转推 WTN
  • 32：语音识别和翻译服务
  • 34：AIGC Gateway
  • 35：AIGC ToB 一站式

示例

请求参数 Property 为 false

  • 请求示例：
GET https://rtc.volcengineapi.com?Action=GetRoomOnlineUsers&Version=2023-11-01&AppId=661e****543cf&RoomId=Room1
  • 返回示例：
{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "GetRoomOnlineUsers",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    },
    "Result": {
        "TotalUser": 2,
        "TotalInvisibleUser": 1,
        "VisibleUserList": [
            "normal_user_1"
        ],
        "InvisibleUserList": [
            "silent_user_1"
        ],
        "RoomExists": true
    }
}

请求参数 Property 为 true

  • 请求示例：
GET https://rtc.volcengineapi.com?Action=GetRoomOnlineUsers&Version=2023-11-01&AppId=661e****543cf&RoomId=Room1&Property=true
  • 返回示例：
{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "GetRoomOnlineUserStatus",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    },
    "Result": {
       "RoomExist": true,
       "VisibleUserList": [
           {
               "UserID": "normalUser1",
               "DeviceType": "ios",
           },
           {
               "UserID": "normalUser2",
               "DeviceType": "mac",
           }
       ],
       "InvisibleUserList": [
           {
               "UserID": "segment1",
               "DeviceType": "linux",
               "MediaProcessingType": 32,
           }
       ]
    }
}

错误码

您可访问公共错误码，获取错误码信息。