Stream transfer

Stream transfer allows Agora to forward a live stream to third-party platforms. With this feature, your app users can publish their live streams on a number of social platforms.

Stream transfer is also known as Rebroadcasting, Restreaming or RTMP Passthrough.

Set transfer configuration

Sets the transfer configuration for an entry point.

HTTP request

PATCH https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/transfer

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

Request body

The request body is in the JSON Object type and contains the following fields:

Field	Type	Description
`enabled`	Bool	Optional. Whether to enable the transfer function: `true`: Enable the transfer function. `false`: (Default) Disable the transfer function.
`callbackUrl`	String	Optional. Your callback URL. If you enable the transfer function, Agora sends requests to this URL to get the platform addresses where the live stream are published. For details, see Transfer callback requirements.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

PATCH https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/transfer HTTP/1.1

Request body

{
    "enabled": true,
    "callbackUrl": "https://example.transfer.com/callback"
}

Response line

HTTP/1.1 200 OK

Get transfer configuration

Gets the transfer configuration for an entry point.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/transfer

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

HTTP response

If the returned HTTP status code is 200, the request is successful, and the response body contains the following fields:

Field	Type	Description
`enabled`	Bool	Whether the transfer function is enabled: `true`: The transfer function is enabled. `false`: The transfer function is disabled.
`callbackUrl`	String	Your callback URL. If you enable the transfer function, Agora sends requests to this URL to get the platform addresses where the live stream are published. For details, see Transfer callback requirements.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

GET https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/transfer HTTP/1.1

Response line

HTTP/1.1 200 OK

Request body

{
  "enabled": true,
  "callbackUrl": "https://example.transfer.com/callback"
}

Transfer callback requirements

If you specify callbackUrl when calling the Set transfer configuration API, Agora sends requests to this URL to get the platform addresses where the live stream are published. The request sent by Agora has the following format:

POST https://example.transfer.com/callback?entry_point={entry_point}&stream_name={stream_name} HTTP/1.1

Where entry_point is the name of the entry point, and stream_name is the name of the live stream.

For such a request, the HTTP response you return must meet the following requirements:

The response is in JSON format.
If the request succeeds, the HTTP status code is 200.
The target addresses are included in the transferUrls field in the response body:
_6{ _6 "transferUrls": [ _6 "rtmp://cdna.example.com/live/testedge", _6 "rtmp://cdnb.example.com/live/testedge" _6 ] _6}

After receiving your HTTP response, Agora starts forwarding the live stream to the specified third-party platforms.

HTTP status code

Status code	Description
200	The request succeeds.
400	The parameter is invalid, for example the `appid` or the `entry_point` is empty, or the `region` parameter value is invalid.
401	Unauthorized (the customer ID and the customer secret do not match).
404	The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500	An internal error occurs in the server, so the server is not able to complete the request.
504	An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.