Include and exclude specific audiences from viewing your Live Video.
For live videos on a Page, you will need:
CREATE_CONTENT
task on the Pagepages_read_user_content
permissionpages_manage_engagement
permissionpages_show_list
permissionpublish_video
permissionFor live videos in a Group, you will need:
publish_video
permissionSend a POST /id
request where id
is the LiveVideo ID and set the targeting
field and its parameters.
curl -i -X POST \
"https://graph.facebook.com/LIVE_VIDEO_ID
?targeting={age_min:17, geo_locations:{countries:["US","CA","MX"]}}
&access_token=ACCESS_TOKEN"
{ "targeting": { "age_max": 65, "age_min": 17, "geo_locations": { "countries": [ "US", "CA", "MX" ] } }, "id": "LIVE_VIDEO_ID" }
For live videos on a Page, you will need:
CREATE_CONTENT
task on the Pagepages_read_engagement
permissionpages_show_list
permissionFor live videos on a Group, you will need:
Send a GET /id
request where id
is the LiveVideo ID with the targeting
field.
curl -i -X GET \
"https://graph.facebook.com/LIVE_VIDEO_ID
?fields=targeting&access_token=ACCESS_TOKEN"
{ "targeting": { "age_max": 65, "age_min": 17, "geo_locations": { "countries": [ "US" "CA", "MX" ] } }, "id": "LIVE_VIDEO_ID" }
There can be a slight delay before a broadcast goes live while we decode its initial streaming data and process any associated API requests. This can make it difficult for on-air talent to know exactly when a broadcast has started. To avoid this problem, LiveVideo objects can be set to accept streaming data but to not go live to audiences until a go-live RTMP message is detected within the streaming data itself. This allows anyone who is able to preview a broadcast to see it, while allowing the streaming encoder to precisely control both the time at which the broadcast goes live for an audience and the first frame that the audience sees.
To enable frame-accurate go-live, first create a LiveVideo object as you normally would and set its status to PREVIEW. Once it has been created, query the LiveVideo object and request the secure_stream_url field with the following nested fields:
secure_stream_url.inband_go_live(require_inband_signal)
This will enable frame-accurate go-live on the LiveVideo object and the API will respond with a new secure stream URL which you can then stream to. You can disregard the initial secure stream url that was sent to you when you first created the LiveVideo object.
The broadcast will go live and be visible to the audience after (1) the broadcast status is set to LIVE (through a Graph API call or a user publishing from Live Producer) and (2) the encoder sends the go-live RTMP message.
An AMF0 packet (type 0x12) containing:
onGoLive
timestamp
For more information, see the RTMP and AMF0 specifications.
Sample request to enable frame-accurate go-live on a LiveVideo.
curl -i -X GET \
"https://graph.facebook.com/v19.0
/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."
Secure stream URL for a LiveVideo object with frame-accurate go-live enabled.
{ "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...", "id": "LIVE_VIDEO_ID" }
Beginning May 25, 2021, the Go Live Dialog will be deprecated. Please visit our Blog post for more information.
We've created a plugin to make the process of Live API integration as easy as possible enabling you to authenticate with Facebook, preview your live stream, and describe your live stream through a pop-up window before going live. This dialog is best suited for those streaming from the client side. Backend integrations should continue to use the API directly.
To initialize a pop-up window with controls that determine where to direct your POST
response insert the following code.
<button id="liveButton">Create Live Stream To Facebook</button> <script> document.getElementById('liveButton').onclick = function() { FB.ui({ display: 'popup', method: 'live_broadcast', phase: 'create', }, function(response) { if (!response.id) { alert('dialog canceled'); return; } alert('{your-stream-url}:' + response.secure_stream_url); FB.ui({ display: 'popup', method: 'live_broadcast', phase: 'publish', broadcast_data: response, }, function(response) { alert("video status: \n" + response.status); }); }); }; </script>
Parameters | Value | Description |
---|---|---|
|
| How the dialog is open in your web page. |
|
| Dialog in create phase allows you to get stream url to upload video; Dialog in publish phase will provide preview and go live button. |
| The response | This parameter is |
In the Create phase pop-up window, choose the live stream destination which can be on any pages or groups you manage. The POST
response will include the stream_url
and secure_stream_url
fields. Either one can be broken out into a server URL and stream key.
The server URL is the first half of the stream_url: rtmp://rtmp-api.facebook.com:80/rtmp/
The stream key is the latter half of the stream_url: 10153307708286557?ds=1&a=AdrRKk4mOaqPbQdxDuk
Response Field | Phase | Description |
---|---|---|
|
| The ID of broadcast video. |
|
| A rtmp url that contains stream server and stream key used to upload the live stream. |
|
| A rtmps url, the stream url with secure protocol. |
|
| String value indicating the status of broadcast. |
In our code snippet, we have an alert
call with the stream_url
. Your client should start streaming using stream_url
. Soon after the stream starts, you will notice a preview of the broadcast appear in the publish phase pop-up window. The dialog enables users to choose privacy settings without adjusting the request's privacy parameter and to set the Live video description, title, and topic tags.
Note: If the publish pop-up window is Offline, ensure that your firewall is not blocking RTMP and that any Adblocker software on your browser is turned off.
When you click Go Live, the dialog will close and within a few seconds, the live stream play on the page or group, according to the chosen destination.
Metadata is injected into the first frame of a live video with frame-accurate start times. Encoders can implement a countdown to alert publishers to the exact start of the video. You can also start and stop the video from the Facebook interface.