Channel management

Your server creates, queries, changes and closes the app's channels with the App Token. For what channels are and how to choose an access mode, see Standalone RTC channels; for request addresses, authentication, pagination and time formats, see Server overview.

You want to	API
Start a meeting or voice room	Create a channel
List ongoing channels	List channels
See a channel's headcount and status	Get a channel
Change the name, business fields or expiry	Update a channel
End the meeting and have everyone leave	Close a channel

Clients only need the channel_id and their own ticket; never give the App Token to clients.

Create a channel

Creates a channel with the channel_id you choose. Safe to retry: with the same ID and parameters while the channel is still open, the existing channel is returned instead of creating another.

PUT/{org_name}/{app_name}/rtc/channels/{channel_id}

Path parameters

For org_name and app_name, see Request address.

Parameter	Type	Description
channel_id	String	Channel ID, 1 to 64 ASCII characters: the first is a letter or digit, the rest letters, digits, _ or -. Case-sensitive

Request body

Field	Type	Required	Description
name	String	Yes	Name; not empty after trimming, at most 128 characters, no control characters. Checked by moderation per the app's settings
media	String	Yes	audio or video
access_mode	String	No	ticket join with a ticket (default) or open any signed-in user, see Access modes and roles
default_role	String	No	Default role: publisher (default) or subscriber
max_participants	Integer	No	Participant limit, 1 to 64, 16 by default
expires_at	String / null	No	Expiry, later than now; omitted or null means no expiry
ext	Object	No	Business extension fields, an empty object by default, JSON at most 4 KB, can't be null

media, access_mode, default_role and max_participants can't be changed after creation.

Example request

curl -X PUT "$IM_API/$ORG/$APP/rtc/channels/meeting-demo" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"项目会议","media":"video","access_mode":"ticket","default_role":"publisher","max_participants":16,"ext":{}}'

Response

Case	Returns
First creation	201 Created, channel is a channel object
Retry: same ID and parameters, channel still open	200 OK with the existing channel
Same ID with different parameters, or the channel with this ID is closed	409, see errors below

Errors

HTTP status	code	details.reason	Description
400	invalid_argument	invalid_channel_id, invalid_request, invalid_role	Invalid channel ID, parameters or role
409	already_exists	channel_id_used	The ID is used by a channel with other parameters or a closed channel
409	limit_exceeded	channel_limit	The app has reached its limit of open channels, see Limits
403	permission_denied	rtc_disabled and others	The app doesn't have audio and video, or channels aren't turned on

For names failing moderation, and common errors such as authentication and rate limiting, see Error codes.

List channels

GET/{org_name}/{app_name}/rtc/channels

Path parameters

org_name and app_name as above.

Query parameters

Parameter	Type	Required	Description
status	String	No	open, closing or closed; omitted returns all
limit	Number	No	Items per page, see Pagination
cursor	String	No	The next_cursor from the previous page. Can't be reused after changing status

Example request

curl "$IM_API/$ORG/$APP/rtc/channels?status=open&limit=20" -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK: items is an array of channel objects, and next_cursor is the cursor for the next page, null on the last page.

Errors

Invalid status or cursor returns 400 invalid_argument; for others see Error codes.

Get a channel

GET/{org_name}/{app_name}/rtc/channels/{channel_id}

Path parameters

org_name, app_name and channel_id as in Create a channel.

Example request

curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo" -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK; channel is a channel object. No media tokens are returned.

Errors

Returns 404 not_found if the channel doesn't exist or doesn't belong to this app.

Update a channel

Changes a channel's name, business fields or expiry. Only channels still open and not expired can be changed.

PATCH/{org_name}/{app_name}/rtc/channels/{channel_id}

Path parameters

As in Create a channel.

Request body

Field	Type	Required	Description
version	Integer	Yes	The channel version you last read
name	String	No	New name, same rules as creation
ext	Object	No	New business extension fields, replaced as a whole
expires_at	String / null	No	New expiry; null removes the expiry

Give at least one of name, ext and expires_at; anything left out is unchanged. Other fields can't be changed, and requests with unknown fields are rejected.

Example request

Replace version with the value you read:

curl -X PATCH "$IM_API/$ORG/$APP/rtc/channels/meeting-demo" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"version":1,"name":"产品会议","expires_at":null}'

Response

Returns 200 OK; channel is the updated channel. version goes up by one when something actually changes, and stays the same when values are unchanged.

Errors

HTTP status	code	Description
400	invalid_argument	Invalid field
409	version_conflict	version isn't the latest; read the channel again and retry
409	conflict	details.reason is channel_closed: the channel is closed or expired

Close a channel

Closes a channel: nobody can join from now on, and existing members start leaving. A closed channel can't be reopened, and its ID can't be reused.

POST/{org_name}/{app_name}/rtc/channels/{channel_id}/close

Path parameters

As in Create a channel.

Request body

Field	Type	Required	Description
reason	String	Yes	Note on closing, not empty, at most 256 characters. For management only; not sent to clients in the channel

Example request

curl -X POST "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/close" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"reason":"会议结束"}'

Response

Returns channel:

Status code	status	Meaning
202 Accepted	closing	Nobody can join; members and media are still being cleaned up, and the server keeps retrying. Don't assume everyone's media has disconnected yet
200 OK	closed	Cleanup is done

Closing again is safe and returns the channel's current status.

Errors

Returns 404 not_found if the channel doesn't exist, 400 invalid_argument for invalid parameters.

Data structures

Channel

Field	Type	Description
channel_id	String	The channel ID you chose
channel_uid	String	Unique ID generated by the server. Store as a string
name	String	Name
media	String	audio or video
access_mode	String	ticket or open
default_role	String	publisher or subscriber
status	String	open, closing or closed
max_participants	Integer	Participant limit
seat_count	Integer	Seats taken, including members joining or leaving
joined_count	Integer	Media-connected headcount as last confirmed
media_state	String	Media room state: idle empty, preparing, active, unknown temporarily unconfirmed, reclaiming
media_observed_at	String / null	When media state was last confirmed
generation	Integer	Media room generation, incremented each time a new media room is prepared
version	Integer	Channel profile version, used by Update a channel
members_version	Integer	Member list version, incremented when members change
ext	Object	Business extension fields
expires_at	String / null	Expiry
closing_at	String / null	When closing started
closed_at	String / null	When closing finished
created_at, updated_at	String	Creation and last change time
close_reason	String	Close reason code
close_note	String	The note given when closing, only returned by server APIs

For how to display headcounts and the unknown state, see Lifecycle and occupancy. Responses with channel profiles and authorization aren't cacheable.