Documentation
Server APIs v2
Room signaling
Add a stream to a room

Add a stream to a room

Last updated：2024-09-30 11:49

1 Description

This interface can be used to add a stream to a specified room. It is commonly used in scenarios where multiple users watch together, such as adding a live stream from a CDN to a specified room, allowing users in the room to access the stream ID and control the live content of the room.

When adding a stream to a specified room, make sure that the room already exists. This interface cannot create a room.If you wish to increase the flow and automatically create corresponding rooms, please contact ZEGO technical support to enable the relevant features.
This interface is usually used in conjunction with the Delete a stream from a room interface, for example, if you need to stop broadcasting a stream to a specific room.

This interface is only used to notify the addition of a stream in the room and does not perform the actual streaming operation. Developers need to call the startPublishingStream interface from their own client to start streaming (or use other streaming methods) so that the added stream can be pulled by the startPlayingStream interface.

On the client side, the ZEGO Express SDK will trigger the following callback to notify the client of the event:

Platform	ZEGO Express SDK callback
iOS/macOS	onRoomStreamUpdate
Android	onRoomStreamUpdate
Windows	onRoomStreamUpdate
Web	roomStreamUpdate

2 Request method and endpoint

Request method: GET
Request endpoint: https://rtc-api.zego.im/?Action=AddStream
Transmission protocol: HTTPS
Rate limit (Rooms with the same AppID): 10 requests/second (Testing environment: 1 requests/second)

3 Request parameters

Listed below are the parameters specific to this request and part of the public request parameters. For the complete list of public request parameters, see Server APIs public request parameters.

Parameter	Type	Required	Description
RoomId	String	Yes	Room ID.
UserId	String	Yes	User ID of the user who performs this operation.
UserName	String	No	User name of the user who performs this operation.
StreamId	String	Yes	Stream ID of the stream to be added.
StreamTitle	String	No	Stream title, with a maximum length of 127 bytes.
ExtraInfo	String	No	Extra stream information, with a maximum length of 1024 bytes.
CensorFlag	Int32	No	Flag indicating whether censorship is allowed. When reviewing a list of room streams, indicates whether the current stream is allowed to be reviewed: 0: Allowed (default). 1: Not allowed. When set to disallow submission, the review service provider will not pull this stream for review. When using stream injection to implement cross-room PK scenarios, it is recommended to set this field to "disallow" to avoid duplicate submission of the same stream in multiple rooms.

When calling this server-side API:

It is not recommended to use the same UserId as the actual users in the room to avoid conflicts with the stream addition behavior of the client SDK. You can use a specific name to identify server-side actions, for example: userId = "Server-Administrator".
If you use the same UserId as the actual users in the room (not recommended), please note the following:
- The client of the corresponding operator UserId will not receive the stream addition callback triggered by this server-side API.
- If the actual user with the UserId in the room does not publish a stream, the stream deletion logic for the corresponding StreamId will be triggered.
- If the actual user with the UserId in the room exits the room, the stream deletion logic for the corresponding StreamId will be triggered.

4 Request example

https://rtc-api.zego.im/?Action=AddStream
 &RoomId=room1
 &UserId=user1
 &UserName=userName
 &StreamId=streamId1
 &StreamTitle=%E6%B5%81%E6%A0%87%E9%A2%98
 &ExtraInfo=%E9%99%84%E5%8A%A0%E4%BF%A1%E6%81%AF
 &CensorFlag=0
&<Public Request Parameters>

5 Response parameters

Parameter	Type	Description
Code	Int32	Return code.
Message	String	Description of the request execution result.
RequestId	String	Request ID.

6 Response example

{
    "Code":0,
    "Message":"success",
    "RequestId":"4443515903608307334"
}

7 Return codes

Listed below are the return codes related to this API. For the complete list of return codes, see Return codes.

Return Code	Description	Suggested Action
123	Failed to set stream information.	Please try again or contact ZEGOCLOUD technical support for assistance.
1012	Multiple users operating on the same stream.	Please check the logic.