查询未加入频道分组的观众列表接口

更新时间：2026-04-14 18:48:58

该文档对应 live-background-aggregate 的 ViewerRecordController.listUnrelationChannelViewer。
这是直播后台登录态接口，userId 由系统根据当前登录账号自动注入，无需前端传入。
用户端接口前缀：/live-bg/v3/user/viewer-record
教师端接口前缀：/live-bg/v3/teacher/viewer-record

1. 查询未加入频道分组的观众列表

接口地址
- GET /live-bg/v3/user/viewer-record/list-unrelation-channel-viewer
- GET /live-bg/v3/teacher/viewer-record/list-unrelation-channel-viewer
请求参数

参数名	必填	类型	说明
channelId	是	Integer	频道ID
name	否	String	姓名
mobile	否	String	手机号
externalViewerId	否	String	外部观众ID
wxOpenId	否	String	微信 OpenId
wxUnionId	否	String	微信 UnionId
nickname	否	String	用户昵称
wxNickName	否	String	微信昵称
source	否	String	用户来源，支持 `WX`、`IMPORT`、`MOBILE`
email	否	String	邮箱
area	否	String	地区
lastCollectMobile	否	String	最近采集手机号
searchKeyword	否	String	关键字，匹配 `nickname` 和 `wxNickName`
viewerId	否	String	观众ID
status	否	String	用户状态
startCreateTime	否	String	注册开始时间，格式：`yyyy-MM-dd HH:mm:ss`
endCreateTime	否	String	注册结束时间，格式：`yyyy-MM-dd HH:mm:ss`
labelIds	否	Array	标签ID集合，最多 10 个
pageNumber	否	Integer	页码，默认 1，最大 1000
pageSize	否	Integer	每页大小，默认 10，最大 1000

处理说明
- 该接口基于用户体系观众列表查询
- 会额外按 channelId 过滤掉已经存在于 channel_viewer_list 表中的观众
- 适用于给频道分组挑选“尚未加入频道用户列表”的候选观众
响应 data 字段

参数名	类型	说明
pageNumber	Integer	当前页码
pageSize	Integer	每页大小
totalPages	Long	总页数
totalItems	Long	总记录数
contents	Array	观众列表

contents 数组元素说明：

参数名	类型	说明
viewerUnionId	String	观众唯一ID
nickname	String	用户昵称
wxNickName	String	微信昵称
mobile	String	手机号
externalViewerId	String	外部观众ID
wxOpenId	String	微信 OpenId
wxUnionId	String	微信 UnionId
source	String	用户来源
name	String	姓名
lastCollectMobile	String	最近采集手机号
email	String	邮箱
area	String	地区
latestAccessIp	String	最近访问 IP
device	String	设备信息
watchDuration	Integer	累计观看时长（秒）
watchChannelCount	Integer	观看频道数
labelIds	Array	标签ID列表
labelNames	Array	标签名称列表
status	String	用户状态
createTime	String	注册时间

请求示例

GET /live-bg/v3/user/viewer-record/list-unrelation-channel-viewer?channelId=123456&searchKeyword=张三&pageNumber=1&pageSize=20

响应示例

{
  "code": 200,
  "status": "success",
  "success": true,
  "requestId": "e9d53b60-2f4c-4f72-8e18-0f0fe8194d52",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalItems": 2,
    "contents": [
      {
        "viewerUnionId": "2_x4r3er86b6h539o4clna3ss39xg3c169",
        "nickname": "张三",
        "wxNickName": "张三微信",
        "mobile": "13800000001",
        "source": "IMPORT",
        "name": "张三",
        "watchDuration": 300,
        "watchChannelCount": 2,
        "createTime": "2026-04-14T10:00:00"
      },
      {
        "viewerUnionId": "2_y5t681288v0316n8z932el5d28w1ka2n",
        "nickname": "李四",
        "mobile": "13800000002",
        "source": "WX",
        "watchDuration": 120,
        "watchChannelCount": 1,
        "createTime": "2026-04-13T18:30:00"
      }
    ]
  }
}

通用响应说明

参数名	类型	说明
code	Integer	状态码
status	String	响应状态，成功为 `success`
success	Boolean	是否成功
requestId	String	请求ID
data	Object	业务返回数据
error	Object	失败时的错误信息

直播服务端 API

查询未加入频道分组的观众列表接口

1. 查询未加入频道分组的观众列表

通用响应说明