Polyv Help Center

Help Center

Live Streaming Server API

Channel User List API

Updated: 2026-04-15 11:51:47

This document corresponds to live-background-aggregate of ChannelViewerListController.
This is a live streaming backend login-required API. userId is automatically injected by the system based on the current logged-in account.
User-side API prefix: /live-bg/v3/user/channel-viewer/list
Teacher-side API prefix: /live-bg/v3/teacher/channel-viewer/list

1. Paginated Query of Channel User List

  • Endpoint
    • GET /live-bg/v3/user/channel-viewer/list/list
    • GET /live-bg/v3/teacher/channel-viewer/list/list
  • Request Parameters
Parameter Required Type Description
channelId Yes Integer Channel ID
groupId No Long Group ID
viewerId No String Viewer ID, max 64 characters
nickname No String User nickname, max 128 characters
mobile No String Phone number, max 32 characters
pageNumber No Integer Page number, default 1
pageSize No Integer Page size, default 10, max 1000

  • Query Notes

    • Supports combined queries by group ID, user nickname, user ID, and phone number
    • Query results are associated with the user system, returning user nickname, phone number, and group name

  • 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 List data

contents Array Element Description:

Parameter Type Description
id Long Primary key ID
channelId Long Channel ID
viewerId String Viewer ID
groupId Long Group ID
groupName String Group name
nickname String User nickname
wxAvatar String WeChat avatar
qwAvatar String WeCom avatar
mobile String Phone number
  • Request Example
GET /live-bg/v3/user/channel-viewer/list/list?channelId=123456&groupId=1&nickname=张三&pageNumber=1&pageSize=20

2. Export Channel User List

  • Endpoint
    • GET /live-bg/v3/user/channel-viewer/list/export
    • GET /live-bg/v3/teacher/channel-viewer/list/export
  • Request Parameters
Parameter Required Type Description
channelId Yes Integer Channel ID
groupId No Long Group ID
viewerId No String Viewer ID
nickname No String User nickname
mobile No String Phone number

  • Processing Notes

    • The export endpoint does not support pagination
    • The return value data is the export task ID, which can be used with the export task query endpoint to check progress and download results

  • Request Example

GET /live-bg/v3/user/channel-viewer/list/export?channelId=123456&groupId=1

3. Add Channel Users

  • Endpoint
    • POST /live-bg/v3/user/channel-viewer/list/save
    • POST /live-bg/v3/teacher/channel-viewer/list/save
  • Request Body Parameters
Parameter Required Type Description
channelId Yes Integer Channel ID
groupId No Long Group ID
viewerIds Yes Array List of viewer IDs, cannot be empty, max 1000

  • Processing Notes

    • Existing viewers will not be added again
    • If groupId is provided, existing viewers will be updated to that group

  • Request Example

{
  "channelId": 123456,
  "groupId": 1,
  "viewerIds": [
    "viewer-a",
    "viewer-b"
  ]
}

4. Delete Channel Users

  • Endpoint
    • POST /live-bg/v3/user/channel-viewer/list/delete
    • POST /live-bg/v3/teacher/channel-viewer/list/delete
  • Request Body Parameters
Parameter Required Type Description
channelId Yes Integer Channel ID
viewerIds Yes Array List of viewer IDs to delete, max 1000

5. Batch Move Channel Users to a Specified Group

  • Endpoint
    • POST /live-bg/v3/user/channel-viewer/list/transfer
    • POST /live-bg/v3/teacher/channel-viewer/list/transfer
  • Request Body Parameters
Parameter Required Type Description
channelId Yes Integer Channel ID
targetGroupId No Long Target group ID. If not provided, the corresponding group will be cleared
viewerIds Yes Array List of viewer IDs, max 1000

6. Import Channel Users

  • Endpoint

    • POST /live-bg/v3/user/channel-viewer/list/import
    • POST /live-bg/v3/teacher/channel-viewer/list/import

  • Request Method

    • multipart/form-data

  • Form Parameters

Parameter Required Type Description
channelId Yes Integer Channel ID
groupId No Long Target group ID
file Yes File Excel file

  • Import Template Notes

    • The header of the 1st column in the Excel file is: 用户手机号

  • Response data Fields

Parameter Type Description
successCount Integer Number of successful imports
failCount Integer Number of failed imports
failFileUrl String URL for the failure details file, may be returned on failure
  • Request Example
curl -X POST 'https://live.polyv.net/live-bg/v3/user/channel-viewer/list/import?channelId=123456&groupId=1' \
  -F 'file=@/tmp/viewer-import.xlsx'

General Response Description

Parameter Type Description
code Integer Status code
status String Response status, success is success
success Boolean Whether the request was successful
requestId String Request ID
data Object Business response data
error Object Error information on failure
联系客服，在线咨询