Skip to main content

Configure callbacks

POST /server/v1/channel/set-callback Authentication: required (see Overview) Register a callback URL; the RTC side notifies your backend when channel or user state changes. Subscribing to any event is optional; events you don’t subscribe to are not pushed. For the full list of events, each event’s field structure, and how callbacks must be answered, see the “Callback events guide”. Request parameters
string
Application scenario (omit when calling from your own backend)
array<string>
List of events to subscribe to. For values, see the “Callback events guide” Example: ["user_join","user_leave","channel_destroy"]
string
Callback URL; must be publicly accessible Example: https://your-domain.com/server/v1/callback/rtc
Request example:
Response parameters data is null Response example:

Get a channel join token

POST /server/v1/channel/grant Authentication: required (see Overview) The first endpoint you use to integrate RTC. Typical flow: your backend confirms the user is allowed into a channel → calls this endpoint to get the token and sid → sends the token to the client, which uses it to call the SDK’s joinChannel. The token is bound to channel+uid and expires. Don’t cache or reuse it; get a new one every time a user joins. Channels don’t need to be created in advance; a channel opens automatically when the first user joins successfully.
  • Getting a token again for the same uid yields a new sid; if that uid is already in the channel, the new session replaces the old one and forces it offline
  • A user with is_audience set to true only receives streams, doesn’t publish, and doesn’t appear in the default user list (query with with_audience to include them)
Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
string
required
Third-party user ID (letters, digits, underscores (_), and hyphens (-) only) (max length 100) Example: 1001
string
required
Display name (max length 100) Example: Alice
object
User properties. When calling this endpoint in response to the agent_join callback, you must put the extend_info received in the callback in here as is (key extend_info); otherwise removing users and turning device video/audio on or off stop working for that device. See the “Callback events guide” for details Example: {"avatar":"https://cdn.example.com/avatar/1001.png"}
boolean
Whether the user is an audience member, like a webinar attendee, who only receives streams, doesn’t interact, and doesn’t publish
string
Network line. The value is a Chinese line name determined by the deployment’s network configuration; leave empty to let the server choose Example: 内网
string
Server group
Request example:
Response parameters
string
ID of this session, generated by the server, used for per-session queries and reconciliation
string
Join credential, issued to the client to call the SDK’s joinChannel
Response example:

Get channel details

POST /server/v1/channel/detail Authentication: required (see Overview) Query the current status and properties of a single channel. Only open channels can be queried—if the channel isn’t open or has been destroyed, the result is empty; for history, use “List channel records”. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
Request example:
Response parameters
string
App ID
string
Channel name
object
Channel properties
integer
Channel creation time Example: 1718250917
integer
Channel info last-modified time Example: 1718250921
Response example:

Get channel user details

POST /server/v1/channel/user-detail Authentication: required (see Overview) Query the real-time status of a single user in the channel, including the tracks they are currently publishing (stream_tracks). When the same uid is online on multiple devices, one of the sessions is returned; to distinguish specific devices, use “List online or offline users” and pick by sid. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
string
required
Third-party user ID (letters, digits, underscores (_), and hyphens (-) only) Example: 1001
Request example:
Response parameters
string
App ID
string
User ID
string
Display name
integer
Device type
string
Device ID
string
Client RTC SDK version
object
User properties
string
Network line
string
Server group ID
integer
User info last-modified time, Unix timestamp in seconds Example: 1718250918
string
Channel name
string
Session ID
boolean
Whether the user is an audience member, like a webinar attendee, who only receives streams
integer
Join time
integer
Leave time
array<object>
Tracks
Response example:

List online channels

POST /server/v1/channel/list Authentication: required (see Overview) List the currently open channels with pagination. A channel opens automatically when the first user joins and is destroyed automatically 2 hours after the last user leaves, so this reflects only current activity; for history, use “List channel records”. Request parameters
boolean
Whether to include details. When false, only basic fields such as the channel name are returned, which greatly reduces the response size; set to true when you need properties and media parameters
integer
Page number, starting from 1 Example: 1
integer
Page size Example: 10
Request example:
Response parameters
string
App ID
string
Channel name
object
Channel properties
integer
Channel creation time Example: 1718250917
integer
Channel info last-modified time Example: 1718250921
Response example:

List online or offline users

POST /server/v1/channel/list-user Authentication: required (see Overview) List channel users with pagination. The same uid joining from multiple devices has multiple records; use sid to tell the sessions apart. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
boolean
Whether to get the online or offline user list. false (default) returns users currently online; true returns users who have left
boolean
Whether to include hidden audience members. Audience members are not returned by default; pass true explicitly
integer
Page number, starting from 1 Example: 1
integer
Page size Example: 10
Request example:
Response parameters
string
App ID
string
User ID
string
Display name
integer
Device type
string
Device ID
string
Client RTC SDK version
object
User properties
string
Network line
string
Server group ID
integer
User info last-modified time, Unix timestamp in seconds Example: 1718250918
string
Channel name
string
Session ID
boolean
Whether the user is an audience member, like a webinar attendee, who only receives streams
integer
Join time
integer
Leave time
array<object>
Tracks
Response example:

List online or offline uids

POST /server/v1/channel/list-uids Authentication: required (see Overview) Uses exactly the same filters as “List online or offline users”, but returns only an array of uid strings, without user details. Suited to scenarios that only need to know “who is in the channel” (such as permission checks and roster comparison); the response is an order of magnitude smaller than the full list. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
boolean
Whether to get the online or offline user list. false (default) returns users currently online; true returns users who have left
boolean
Whether to include hidden audience members. Audience members are not returned by default; pass true explicitly
integer
Page number, starting from 1 Example: 1
integer
Page size Example: 10
Request example:
Response parameters
array<string>
Response data
Response example:

Update channel info

POST /server/v1/channel/update Authentication: required (see Overview) Update a channel’s properties. The channel must already be open; otherwise the update has no effect. Changes are synced to all clients in the channel via signaling. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
object
Channel properties. Replaced as a whole, not merged field by field—include any fields you want to keep Example: {"watermark_disabled":true}
Request example:
Response parameters data is null Response example:

Update user info

POST /server/v1/channel/update-user Authentication: required (see Overview) Update a user’s display name, properties, or audience status in the channel. Changes are synced to other users in the channel. Changing a user already in the channel to audience downgrades them to receive-only, and the tracks they have published are stopped. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
string
required
User ID (letters, digits, underscores (_), and hyphens (-) only) Example: 1001
string
Display name; omit to leave unchanged Example: Alice
object
User properties; replaced as a whole Example: {"avatar":"https://cdn.example.com/avatar/1001.png"}
boolean
Whether the user is an audience member, like a webinar attendee, who only receives streams
array<object>
Tracks
Request example:
Response parameters data is null Response example:

Send a custom message

POST /server/v1/channel/send-custom-msg Authentication: required (see Overview) Broadcast a custom message to the channel over the signaling channel; client SDKs receive it as an event. Suited to lightweight business signaling such as chat, raising hands, and voting; not suited to large data or high-frequency messages. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
string
required
Message command, defined by you; the client dispatches on it Example: chat
any
Message body, any JSON; you define the structure Example: &#123;"text": "i love srtc"&#125;
string
Sender ID, used by the client to show “who sent it”; can be empty for system messages sent by the server (letters, digits, underscores (_), and hyphens (-) only) Example: 1001
string
Sender display name Example: Alice
array<string>
List of recipient IDs (empty sends to the whole channel) Example: ["1002","1003"]
boolean
Whether the message is important. Important messages are resent after reconnecting to make sure they arrive, at the cost of slightly higher latency
Request example:
Response parameters data is null Response example:

Remove a user from the channel

POST /server/v1/channel/kick-user Authentication: required (see Overview) Remove the specified user from the channel. Their client receives a removal event, and the user_leave callback is triggered (reason indicates the user was removed). Removal is a one-time action, not a ban—a removed uid can join again after getting a new token. To prevent rejoining, block token issuance on your own side. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
string
required
Third-party user ID (letters, digits, underscores (_), and hyphens (-) only) Example: 1001
Request example:
Response parameters data is null Response example:

Open a channel manually

POST /server/v1/channel/open Authentication: required (see Overview) By default a channel opens automatically when the first user joins, so you don’t need to call this endpoint. It’s needed in only one scenario: you want to set the channel’s properties before anyone joins (such as a watermark switch or your own room configuration), so the first user to join reads the correct configuration, avoiding the “join first, then change properties” timing problem. A channel is destroyed automatically if no one joins within 2 hours after it opens, or 2 hours after the last user leaves. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
object
Channel properties Example: {"watermark_disabled":true}
Request example:
Response parameters data is null Response example:

Destroy a channel

POST /server/v1/channel/destroy Authentication: required (see Overview) Destroy the channel immediately. Everyone in the channel is forced to leave, and the channel_destroy callback is triggered. Normally a channel is destroyed automatically 2 hours after the last user leaves, so you don’t need to call this. This endpoint is for scenarios that need to reclaim a channel immediately (such as an administrator forcibly ending it). In-progress recording tasks in the channel are stopped as well. After destruction, a channel with the same name can be opened again, but as a new channel record. Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
Request example:
Response parameters data is null Response example:

List channel records

POST /server/v1/channel/list-record Authentication: required (see Overview) Query a channel’s history of opens. A channel name opened multiple times has multiple records, each corresponding to a complete lifecycle (open_at → destroy_at). A destroy_at of 0 in the response means the channel is still in progress. Request parameters
string
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
integer
Start time, Unix timestamp in seconds, filtered by channel open time; 0 means no limit Example: 1718194666
integer
End time, Unix timestamp in seconds; 0 means no limit Example: 1718799878
string
Sort order (sortable fields: open_at, destroy_at)
integer
Page number, starting from 1 Example: 1
integer
Page size Example: 10
Request example:
Response parameters
string
Channel record ID Example: snp3rp
string
App ID
string
Channel
object
Properties
integer
Open time
integer
Destroy time
integer
Destroy reason
Response example:

List join and leave records

POST /server/v1/channel/list-user-record Authentication: required (see Overview) Query users’ join/leave records; one user joining multiple times has multiple records, distinguished by sid. This is the main data source for duration-based billing and attendance auditing.
  • A leave_at of 0 in the response means the user is still in the channel
  • Duration of one session = leave_at - join_at (seconds)
Request parameters
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire
string
User ID; leave empty for no filter (letters, digits, underscores (_), and hyphens (-) only) Example: 1001
string
Display name; leave empty for no filter Example: Alice
integer
Start time, Unix timestamp in seconds, filtered by join time; 0 means no limit Example: 1718194666
integer
End time, Unix timestamp in seconds; 0 means no limit Example: 1718799878
boolean
Whether to include hidden audience members
string
Sort order (sortable fields: join_at, leave_at)
integer
Page number, starting from 1 Example: 1
integer
Page size Example: 10
Request example:
Response parameters
string
Join/leave record ID Example: syd30d
string
App ID
string
Channel
string
Session ID; distinguishes multiple joins by the same uid Example: ff6u9joh5c1a0toa7dj1
string
User ID Example: 1001
string
Display name
boolean
Whether the user is an audience member, like a webinar attendee, who only receives streams
integer
Device type
string
Device ID
string
Client RTC SDK version
object
Properties
integer
Join time
integer
Leave time
integer
Leave reason
Response example:

Get online user counts

POST /server/v1/channel/online-user-num Authentication: required (see Overview) Query the current online user counts of multiple channels in a single request; suited to list pages. The data in the response maps “channel name → user count”, such as {"fire": 4}; channels that aren’t open or don’t exist are omitted from the result (rather than returning 0). To tell them apart, compare against the channels in your request. Request parameters
array<string>
required
List of channel names Example: ["fire","water"]
boolean
Whether to include hidden audience members
Request example:
Response parameters
integer
Keys are dynamic; see the description above
Response example:

Get a channel’s historical user count

POST /server/v1/channel/history-join-num Authentication: required (see Overview) Get the historical participation of a channel within a specified time range.
  • user_num is deduplicated by uid and answers “how many people took part”
  • user_times is not deduplicated and answers “how many times people joined in total”
Request parameters
string
required
Channel name Example: fire
integer
required
Start time, Unix timestamp in seconds Example: 1718194666
integer
End time, Unix timestamp in seconds; 0 means up to the current moment Example: 1718799878
boolean
Whether to include hidden audience members
Request example:
Response parameters
integer
Number of users, deduplicated by uid Example: 60
integer
Number of joins; repeated joins by the same person are counted each time Example: 1935
Response example:

Get today’s channel statistics

POST /server/v1/channel/today Authentication: required (see Overview) Summary of your own app’s channel opens and total duration today. No request parameters—the scope is determined by the app identity from authentication, so only your data is returned. Only destroyed channels (destroy_at greater than 0) are counted; channels still in progress are excluded, so the numbers grow as the day goes on. The time zone is fixed to UTC+8 (Asia/Shanghai). Request parameters None Response parameters
integer
Snapshot time: Unix timestamp in seconds when the response was generated Example: 1718250917
integer
Number of channel opens today Example: 120
integer
Total channel duration today (seconds) Example: 43200
Response example:

Get daily channel statistics

POST /server/v1/channel/stats Authentication: required (see Overview) Channel opens and duration aggregated by day, for drawing trend charts. The scope is determined by the app identity from authentication, so only your own app’s data is returned.
  • Only destroyed channels (destroy_at greater than 0) are counted; channels still in progress are excluded
  • Dates with no data are omitted from the result (no zero-filling); fill the gaps yourself when plotting
Request parameters
integer
Start time, Unix timestamp in seconds; 0 means the last 31 days Example: 1718194666
integer
End time, Unix timestamp in seconds; 0 or a time later than now is treated as now Example: 1718799878
Request example:
Response parameters
string
Date, in YYYY-MM-DD format Example: 2024-06-12
integer
Number of channel opens that day Example: 120
integer
Total channel duration that day (seconds) Example: 43200
Response example: