Channel sessions and members
Your server uses the App Token to see who's in a channel, remove someone, or ban them from coming back. Usernames in these APIs are the app's usernames, not the media_identity in the media room, and these APIs never issue media credentials on users' behalf. For path prefixes and pagination, see Server overview.
| You want to | API | Effect |
|---|---|---|
| See who's in the channel | List channel sessions | |
| Make someone leave this time | Remove a user | Ends their current session; they can join again later |
| Keep someone out | Ban a user | Ends their current session, revokes their unused tickets, and they can't join afterwards |
| Cancel someone's unused invitation | Revoke tickets | Sessions already joined aren't affected |
| Let a banned user back | Unban a user | ticket channels need a new ticket |
List channel sessions
/{org_name}/{app_name}/rtc/channels/{channel_id}/sessionsPath parameters
For org_name, app_name and channel_id, see Channel management.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | String | No | joining, joined, leaving or left. Omitted returns the first three (currently in the channel); pass status=left for sessions that have left |
limit | Number | No | Items per page, see Pagination |
cursor | String | No | The next_cursor from the previous page |
Example request
curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/sessions?status=joined&limit=20" -H "Authorization: Bearer $APP_TOKEN"Response
Returns 200 OK: items is an array of sessions, and next_cursor is null on the last page. Session fields are in Client channel sessions; here leave_note, the note given when removing or banning, is also returned. Sessions that have left are kept for 90 days.
Errors
Invalid status or cursor returns 400 invalid_argument; a channel that doesn't exist returns 404 not_found.
Remove a user
Ends the user's current session in the channel. They can still join again later, and their unused tickets stay valid.
/{org_name}/{app_name}/rtc/channels/{channel_id}/members/{username}/removePath parameters
org_name, app_name and channel_id as above.
| Parameter | Type | Description |
|---|---|---|
username | String | Username to remove |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
operation_id | String | Yes | ID of this operation, 1 to 64 printable ASCII characters, no spaces. Retry with the same ID after a timeout |
reason | String | Yes | Note, not empty, at most 256 characters |
The body can't contain usernames.
Example request
curl -X POST "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/members/alice/remove" \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"operation_id":"remove-meeting-demo-alice-001","reason":"主持人移出"}'Response
Returns operation_id and the ended sessions: 202 Accepted while media is still being cleaned up, 200 OK once done. Retrying with the same operation_id and parameters doesn't run it again.
Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | Invalid parameters |
| 404 | not_found | The channel or user doesn't exist |
| 409 | conflict | details.reason is idempotency_conflict: the same operation_id was used with different parameters |
Get a user's ban
Gets a user's ban record in this channel, including the version needed to change or lift it.
/{org_name}/{app_name}/rtc/channels/{channel_id}/bans/{username}Path parameters
As in Remove a user.
Example request
curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans/alice" -H "Authorization: Bearer $APP_TOKEN"Response
Returns 200 OK; ban is the ban record, null if the user was never banned. The record may already be lifted or expired; check status and expires_at to see whether it's in effect now.
Errors
Returns 404 not_found if the channel or user doesn't exist.
Ban a user
Bans a user: their current session starts leaving, their unused tickets are invalidated, and they can't join this channel afterwards. Also used to change an existing ban's expiry and note.
/{org_name}/{app_name}/rtc/channels/{channel_id}/bans/{username}Path parameters
As in Remove a user.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
version | Integer | Yes | 0 when there's no ban record; otherwise the version read with Get a user's ban |
reason | String | Yes | Note, not empty, at most 256 characters |
expires_at | String / null | No | Expiry, later than now; omitted or null bans permanently |
Example request
The user has no ban record yet:
curl -X PUT "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans/alice" \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"version":0,"reason":"违规参与","expires_at":null}'Response
Returns ban: 201 Created for a first ban, 200 OK for a change or a retry of the same request. Media may still be disconnecting when this succeeds.
Errors
| HTTP status | code | Description |
|---|---|---|
| 400 | invalid_argument | Invalid parameters |
| 409 | version_conflict | version isn't the latest; read again and resubmit |
| 409 | conflict | details.reason is channel_closed: the channel is closed |
Unban a user
/{org_name}/{app_name}/rtc/channels/{channel_id}/bans/{username}Path parameters
As in Remove a user.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
version | Integer | Yes | The latest version read with Get a user's ban |
Example request
curl -X DELETE "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans/alice" \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"version":1}'Response
Returns 200 OK; ban is the lifted record, null if there was none. Lifting again also succeeds.
Unbanning doesn't restore tickets invalidated by the ban or sessions it ended: ticket channels need a new ticket.
Errors
Returns 409 version_conflict when version isn't the latest, so an old version number can't accidentally lift a ban added later.
List active bans
Lists bans currently in effect in the channel. For lifted or expired records, use Get a user's ban.
/{org_name}/{app_name}/rtc/channels/{channel_id}/bansPath parameters
As in List channel sessions.
Query parameters
limit and cursor, see Pagination.
Example request
curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans?limit=20" -H "Authorization: Bearer $APP_TOKEN"Response
Returns 200 OK: items are the ban records currently in effect, and next_cursor is null on the last page.
Errors
Invalid cursor returns 400 invalid_argument; a channel that doesn't exist returns 404 not_found.
Data structures
Ban (ban record):
| Field | Type | Description |
|---|---|---|
username | String | Username |
status | String | active or revoked (lifted). For active, also check whether expires_at has passed |
expires_at | String / null | Expiry, null for permanent |
reason | String | Ban note. For management only; never appears in client member lists or media credentials |
version | Integer | Version, used for changing and lifting |
created_at, updated_at | String | Creation and last change time |