Overview
This API removes one or more sub-rooms from a specified main room's relay list. Once removed, the sub-rooms stop receiving the main room's mixed stream relay and revert to independent rooms.
Use Cases
Event Conclusion: Remove branch venue rooms from the main stage after a live event ends.
Dynamic Adjustment: Reduce the number of relay rooms during operation.
Room Recovery: Restore sub-rooms to independent operation so they no longer act as relay destinations.
Note:
Per-Request Limit: Up to 5 sub-rooms per request.
Idempotency: Removing a non-existent relay relationship will not cause an error (but the child room must exist and belong to the specified main room).
Template Restoration: After removal, the child room automatically reverts to its original layout template from creation time.
Request URL
Example
https://xxxxxx/v4/live_engine_http_srv/del_relay_room?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
Query Parameters
The table below lists only the parameters relevant to this API call and their descriptions. For more details, refer to the REST API Overview. |
xxxxxx | The reserved domain for the country/region where the SDKAppID is located: Others in China: console.tim.qq.com Singapore: adminapisgp.im.qcloud.com Silicon Valley: adminapiusa.im.qcloud.com Jakarta: adminapiidn.im.qcloud.com |
v4/live_engine_http_srv/del_relay_room | Remove Relay Child Room API. |
sdkappid | |
identifier | |
usersig | Signature generated for the application admin account. For instructions, see Generate UserSig. |
random | Random 32-bit unsigned integer, range 0 - 4294967295. |
contenttype | Request format, fixed value json. |
Rate Limits
Within the same SDKAppID, each main room allows at most 1 relay write operation per second (AddRelayRoom / DelRelayRoom share the same rate limit).
Request Parameters
The request body must be in JSON format.
Request Example
{
"RoomId": "main-room-001",
"RelayRoomIdList": ["child-room-002", "child-room-003"]
}
Field Descriptions
|
RoomId | String | Yes | Main room ID. Only the room owner or admin of the main room can remove sub-rooms. |
RelayRoomIdList | Array of String | Yes | List of child room IDs to remove: Up to 5 per request; sub-rooms must exist and belong to the specified main room; otherwise the corresponding child room returns an error. |
Effects After Removal
|
Mix Stream | Relays main room's mixed content. | Reverts to child room's own mix stream (if seats are occupied), or stops mixing (if no one on seats). |
Layout Template | Uses relay template mapped from main room. | Reverts to the original template from creation. |
Connection/TakeSeat/PK | Disabled. | Restored to normal, no longer restricted. |
RelayRole | Sub (2). | None (0). |
Response Parameters
When the API returns HTTP 200, check the ErrorCode in the response body to determine business logic success.
Success Response Example
{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"RequestId": "Id-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"Response": {
"ResultList": [
{
"RoomId": "child-room-002",
"ErrorCode": 0,
"ErrorInfo": ""
},
{
"RoomId": "child-room-003",
"ErrorCode": 0,
"ErrorInfo": ""
}
]
}
}
Field Descriptions
|
ActionStatus | String | Request processing result: OK: processed successfully; FAIL: failed. |
ErrorCode | Integer | Error code: 0: success; Non-zero: overall request failed. |
ErrorInfo | String | Error information. |
RequestId | String | Unique request ID, returned with every request. Provide this when troubleshooting issues. |
Response.ResultList | Array | Operation result list for each child room, in the same order as RelayRoomIdList in the request. |
Response.ResultList[i].RoomId | String | Child room ID. |
Response.ResultList[i].ErrorCode | Integer | Operation result for this child room. 0 indicates success; non-zero indicates failure. |
Response.ResultList[i].ErrorInfo | String | Error information for this child room. |
Error Codes
For common error codes (60000 to 79999), refer to the Error Codes documentation. The following are the private error codes specific to this API: |
100001 | Internal server error. Please retry. |
100002 | Invalid request parameters. Check the request based on the error description. Common causes: child room does not exist, RelayRoomIdList is empty. |
100006 | Permission denied. Common causes: not a REST API call, caller is neither the room owner nor an admin, child room does not belong to the specified main room. |
100012 | Rate limit exceeded. Each main room allows at most 1 relay write operation per second. |
100027 | Operation in progress. Another relay write operation is being executed for the same main room. Please retry later. |
Additional Notes
Behavior When a Child Room Is Dismissed
When a room that is currently bound as a relay child room is dismissed (via Dismiss Room), the system automatically performs the following cleanup: 1. Stops the child room's MCU mix stream task.
2. Removes the child room from the main room's relay list.
No additional call to DelRelayRoom is needed.
Behavior When the Main Room Is Dismissed
When the main room is dismissed, the system automatically iterates through all sub-rooms and performs cleanup:
1. Stops or reverts each child room's mix stream task to independent mixing.
2. Clears the relay role flag for each child room.
3. Deletes the main room's child room list.
Operational Best Practices
Recommended Workflow for Ending a Live Session
1. Call this API to remove all relay sub-rooms first.
2. Then dismiss the sub-rooms and main room in sequence.
Note:
When the main room is directly dismissed, the system automatically cleans up all sub-rooms' relay relationships. sub-rooms are not dismissed — they only revert to independent rooms. However, explicit removal is recommended to ensure state consistency.
Sub-room State After Removal
After the relay relationship is removed, the child room is fully restored to an independent room:
Can perform TakeSeat, Connection, and PK normally;
If seats are occupied, the child room's own template mix stream resumes automatically;
If no one is on seats, the mix stream task stops.
FAQ
What do viewers in the child room see after removal?
If seats in the child room are occupied, viewers will see the child room's own mix stream. If no one is on seats, viewers will see no content (mix stream stops).
Do I need to call the remove API before dismissing a child room?
No. When a child room is dismissed, the system automatically removes it from the main room's relay list. No additional API call is needed.
Will sub-rooms be dismissed when the main room is dismissed?
No. When the main room is dismissed, the system only cleans up relay relationships. sub-rooms revert to independent rooms and continue to exist.
Is there a rate limit for the remove operation?
Yes. Each main room allows at most 1 relay write operation per second (add and remove share the same rate limit).
Reference
Dismiss Room: Relay relationships are automatically cleaned up when a room is dismissed.