Query Viewer List Not in Channel Group API

Updated: 2026-04-14 18:48:58

This document corresponds to live-background-aggregate of ViewerRecordController.listUnrelationChannelViewer.
This is a live streaming backend login-required API. userId is automatically injected by the system based on the current logged-in account and does not need to be passed by the frontend.
User-side API prefix: /live-bg/v3/user/viewer-record
Teacher-side API prefix: /live-bg/v3/teacher/viewer-record

1. Query Viewer List Not in Channel Group

API Endpoint
- GET /live-bg/v3/user/viewer-record/list-unrelation-channel-viewer
- GET /live-bg/v3/teacher/viewer-record/list-unrelation-channel-viewer
Request Parameters

Parameter	Required	Type	Description
channelId	Yes	Integer	Channel ID
name	No	String	Name
mobile	No	String	Phone number
externalViewerId	No	String	External viewer ID
wxOpenId	No	String	WeChat OpenId
wxUnionId	No	String	WeChat UnionId
nickname	No	String	User nickname
wxNickName	No	String	WeChat nickname
source	No	String	User source, supports `WX`, `IMPORT`, `MOBILE`
email	No	String	Email
area	No	String	Region
lastCollectMobile	No	String	Last collected phone number
searchKeyword	No	String	Keyword, matches `nickname` and `wxNickName`
viewerId	No	String	Viewer ID
status	No	String	User status
startCreateTime	No	String	Registration start time, format: `yyyy-MM-dd HH:mm:ss`
endCreateTime	No	String	Registration end time, format: `yyyy-MM-dd HH:mm:ss`
labelIds	No	Array	Label ID list, maximum 10
pageNumber	No	Integer	Page number, default 1, max 1000
pageSize	No	Integer	Page size, default 10, max 1000

Processing Notes
- This API is based on the user system viewer list query
- It additionally filters out viewers already present in the channelId table based on channel_viewer_list
- Suitable for selecting candidate viewers who have "not yet joined the channel user list" when assigning channel groups
Response data Fields

Parameter	Type	Description
pageNumber	Integer	Current page number
pageSize	Integer	Page size
totalPages	Long	Total pages
totalItems	Long	Total records
contents	Array	Viewer list

contents Array Element Description:

Parameter	Type	Description
viewerUnionId	String	Unique viewer ID
nickname	String	User nickname
wxNickName	String	WeChat nickname
mobile	String	Phone number
externalViewerId	String	External viewer ID
wxOpenId	String	WeChat OpenId
wxUnionId	String	WeChat UnionId
source	String	User source
name	String	Name
lastCollectMobile	String	Last collected phone number
email	String	Email
area	String	Region
latestAccessIp	String	Last access IP
device	String	Device information
watchDuration	Integer	Cumulative watch duration (seconds)
watchChannelCount	Integer	Number of channels watched
labelIds	Array	Label ID list
labelNames	Array	Label name list
status	String	User status
createTime	String	Registration time

Request Example

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

Response Example

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

General Response Description

Parameter	Type	Description
code	Integer	Status code
status	String	Response status, success is `success`
success	Boolean	Whether successful
requestId	String	Request ID
data	Object	Business response data
error	Object	Error information on failure

Live Streaming Server API

Query Viewer List Not in Channel Group API

1. Query Viewer List Not in Channel Group

General Response Description