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/rtcdata 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)
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only)
Example:
firestring
required
Third-party user ID (letters, digits, underscores (_), and hyphens (-) only) (max length 100)
Example:
1001string
required
Display name (max length 100)
Example:
Aliceobject
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
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
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:
firestring
App ID
string
Channel name
object
Channel properties
integer
Channel creation time
Example:
1718250917integer
Channel info last-modified time
Example:
1718250921Get 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:
firestring
required
Third-party user ID (letters, digits, underscores (_), and hyphens (-) only)
Example:
1001string
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:
1718250918string
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
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:
1integer
Page size
Example:
10string
App ID
string
Channel name
object
Channel properties
integer
Channel creation time
Example:
1718250917integer
Channel info last-modified time
Example:
1718250921List 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:
fireboolean
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:
1integer
Page size
Example:
10string
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:
1718250918string
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
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:
fireboolean
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:
1integer
Page size
Example:
10array<string>
Response data
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:
fireobject
Channel properties. Replaced as a whole, not merged field by field—include any fields you want to keep
Example:
{"watermark_disabled":true}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:
firestring
required
User ID (letters, digits, underscores (_), and hyphens (-) only)
Example:
1001string
Display name; omit to leave unchanged
Example:
Aliceobject
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
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:
firestring
required
Message command, defined by you; the client dispatches on it
Example:
chatany
Message body, any JSON; you define the structure
Example:
{"text": "i love srtc"}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:
1001string
Sender display name
Example:
Alicearray<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
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:
firestring
required
Third-party user ID (letters, digits, underscores (_), and hyphens (-) only)
Example:
1001data 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:
fireobject
Channel properties
Example:
{"watermark_disabled":true}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:
firedata 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:
fireinteger
Start time, Unix timestamp in seconds, filtered by channel open time; 0 means no limit
Example:
1718194666integer
End time, Unix timestamp in seconds; 0 means no limit
Example:
1718799878string
Sort order (sortable fields: open_at, destroy_at)
integer
Page number, starting from 1
Example:
1integer
Page size
Example:
10string
Channel record ID
Example:
snp3rpstring
App ID
string
Channel
object
Properties
integer
Open time
integer
Destroy time
integer
Destroy reason
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)
string
required
Channel name (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only)
Example:
firestring
User ID; leave empty for no filter (letters, digits, underscores (_), and hyphens (-) only)
Example:
1001string
Display name; leave empty for no filter
Example:
Aliceinteger
Start time, Unix timestamp in seconds, filtered by join time; 0 means no limit
Example:
1718194666integer
End time, Unix timestamp in seconds; 0 means no limit
Example:
1718799878boolean
Whether to include hidden audience members
string
Sort order (sortable fields: join_at, leave_at)
integer
Page number, starting from 1
Example:
1integer
Page size
Example:
10string
Join/leave record ID
Example:
syd30dstring
App ID
string
Channel
string
Session ID; distinguishes multiple joins by the same uid
Example:
ff6u9joh5c1a0toa7dj1string
User ID
Example:
1001string
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
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
integer
Keys are dynamic; see the description above
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”
string
required
Channel name
Example:
fireinteger
required
Start time, Unix timestamp in seconds
Example:
1718194666integer
End time, Unix timestamp in seconds; 0 means up to the current moment
Example:
1718799878boolean
Whether to include hidden audience members
integer
Number of users, deduplicated by uid
Example:
60integer
Number of joins; repeated joins by the same person are counted each time
Example:
1935Get 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:
1718250917integer
Number of channel opens today
Example:
120integer
Total channel duration today (seconds)
Example:
43200Get 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
integer
Start time, Unix timestamp in seconds; 0 means the last 31 days
Example:
1718194666integer
End time, Unix timestamp in seconds; 0 or a time later than now is treated as now
Example:
1718799878string
Date, in YYYY-MM-DD format
Example:
2024-06-12integer
Number of channel opens that day
Example:
120integer
Total channel duration that day (seconds)
Example:
43200