To broadcast a live video, you must first create a LiveVideo
object. The LiveVideo
object represents the broadcast, and you can manipulate the object's properties to control the broadcast's settings. Upon creation, the API will return the LiveVideo
object's ID and a stream URL, which you can pass to your encoder and use to stream data to the LiveVideo
object.
To broadcast on a User profile, get a User access token with the publish_video
permission and send a request to:
POST /{user-id}/live_videos?status=LIVE_NOW
Refer to the /live_videos
edge reference to see additional query string parameters you can include to describe the broadcast, such as a title and description.
Upon success, the API will create a LiveVideo
object on the User and return a secure_stream_url
and the LiveVideo
object's id
. The broadcast will appear in a post on the User's profile as soon as you send data to the secure stream URL. You can query the LiveVideo
object to monitor the broadcast's health and to end the broadcast.
curl -i -X POST \
"https://graph.facebook.com/{user-id}/live_videos
?status=LIVE_NOW
&title=Today%27s%20Live%20Video
&description=This%20is%20the%20live%20video%20for%20today.
&access_token={access-token}"
{ "id": "1953020644813104", "stream_url": "rtmp://rtmp-api.facebook...", "secure_stream_url":"rtmps://rtmp-api.facebook..." }
To broadcast a live video on a Page, get a Page access token of an admin of the Page with the pages_read_engagement
and
pages_manage_posts
permissions, then send a request to:
POST /{page-id}/live_videos?status=LIVE_NOW
Refer to the /live_videos
edge reference to see additional query string parameters you can include to describe the broadcast, such as a title and description.
Upon success, the API will create a LiveVideo
object on the Page and return a secure_stream_url
and the LiveVideo
object's id
. The broadcast will appear in a post on the Page as soon as you send data to the secure stream URL. You can query the LiveVideo
object to monitor the broadcast's health and to end the broadcast.
curl -i -X POST \
"https://graph.facebook.com/{page-id}/live_videos
?status=LIVE_NOW
&title=Today%27s%20Page%20Live%20Video
&description=This%20is%20the%20live%20video%20for%20the%20Page%20for%20today
&access_token=EAAC..."
{ "id": "1953020644813108", "stream_url": "rtmp://rtmp-api.facebook...", "secure_stream_url":"rtmps://rtmp-api.facebook..." }
Before you can broadcast a live video on a Group, the Group must install your app. A Group admin can do this on www.facebook.com by viewing the Group, going to Edit Group Settings > Apps > Add Apps, and adding your app.
To broadcast a live video on a Group that has installed your app, get a User access token of an admin of the Group with the publish_video
permission, then send a request to:
POST /{group-id}/live_videos?status=LIVE_NOW
Refer to the /live_videos
edge reference to see additional query string parameters you can include to describe the broadcast, such as a title and description.
Upon success, the API will create a LiveVideo
object on the Group and return a secure_stream_url
and the LiveVideo
object's id
. The broadcast will appear in a post on the Group as soon as you send data to the secure stream URL. You can query the LiveVideo
object to monitor your broadcast's health and to end the broadcast.
curl -i -X POST \
"https://graph.facebook.com/{group-id}/live_videos
?status=LIVE_NOW
&title=Today%27s%20Group%20Live%20Video
&description=This%20is%20the%20live%20video%20for%20the%20group%20for%20today
&access_token={access-token}"
{ "id": "1953020644813108", "stream_url": "rtmp://rtmp-api.facebook...", "secure_stream_url":"rtmps://rtmp-api.facebook..." }
You can read a LiveVideo
object to get the broadcast stream's preview URLs and data on streaming health, such as bitrates and framerates. Stream health data refreshes every 2 seconds, so limit queries to no more than once every 2 seconds. A stream timeout will be detected and reported after 4 seconds of no data being received.
To read a LiveVideo
object, get an appropriate User or Page access token with the publish_video
permission, then send a query to:
GET /{live-video-id}?fields={fields}
Use the {fields}
parameter to specify the LiveVideo object fields you want returned. For example, here's a request to get the ingest_streams
on the LiveVideo
object, which includes data about stream health:
curl -i -X GET \
"https://graph.facebook.com/{live-video-id}
?fields=ingest_streams
&access_token={access-token}"
{ "ingest_streams": [ { "stream_id": "0", "stream_url": "rtmp://rtmp-api.facebook...", "secure_stream_url": "rtmps://rtmp-api.facebook...", "is_master": true, "stream_health": { "video_bitrate": 4024116, "video_framerate": 60, "video_gop_size": 2000, "video_height": 720, "video_width": 1280, "audio_bitrate": 128745.4921875 }, "id": "1914910145231512" // Ingest stream ID } ], "id": "{your-live-video-id}" }
Response Properties
Field Name | Description |
---|---|
audio_bitrate | Bits per second of the incoming audio stream. |
is_master |
|
secure_stream_url | The secure RTMPS ingest URL for the Live Video ID being queried. |
stream_url | The RTMP ingest URL for the Live Video ID being queried. |
video_bitrate | Bits per second of the incoming video stream. |
video_framerate | Frames per second of the incoming video stream. |
video_gop_size | GOP (group of pictures) size in milliseconds. |
video_height | Height in pixels of the incoming video frame. |
video_width | Width in pixels of the incoming video frame. |
To end a broadcast, stop streaming live video data from your encoder to the stream URL or send a request to:
POST /{live-video-id}?end_live_video=true
This sets the LiveVideo
object's status to VOD
and saves it as a video-on-demand (VOD) so it can be viewed later.
Upon success, the API will return the LiveVideo
object's ID.
curl -i -X POST \
"https://graph.facebook.com/{live-video-id}
?end_live_video=true
&access_token={access-token}"
{ "id": "10213570560993813" }
You can perform a GET
operation on the LiveVideo ID to confirm that its status has been set to VOD
:
GET /{live-video-id}?fields=status
{ "status": "VOD", // Broadcast ended, saved as VOD "id": "10213570560993813" }
To delete a broadcast that has ended and saved as a VOD, send a request to:
curl -i -X DELETE \
"https://graph.facebook.com/{live-video-id}?access_token={access-token}"
{ success: true }
To get error code data associated with a broadcast, send a request to:
GET /{live-video-id}?fields=errors
The API will respond with the error code
, type
, message
, and a timestamp
.
curl -i -X GET \
"https://graph.facebook.com/{live-video-id}
?fields=errors
&access_token={access-token}"
{ "errors": { "data": [ { "error_code": 1969004, "error_type": "stream", "error_message": "Video signal lost", "creation_time": "2018-12-05T23:58:52+0000" }, { "error_code": 1969004, "error_type": "stream", "error_message": "Video signal lost", "creation_time": "2018-12-05T23:58:52+0000" }, { "error_code": 0, "error_type": "info", "error_message": "Live Service received the video signal", "creation_time": "2018-12-05T23:58:02+0000" }, { "error_code": 0, "error_type": "info", "error_message": "Live Service received the video signal", "creation_time": "2018-12-05T23:58:02+0000" } ] }, "id": "{your-live-video-id}" }
error_subcode | Error Summary | Description |
---|---|---|
COPYRIGHT__LIVE_COPYRIGHT_VIOLATION | Live Copyright Violation | Your live video has been stopped because it may contain audio or visual content that belongs to a different Page. |
VIDEO__CREATE_FAILED | Upload Problem | There was a problem and your video was not uploaded. Please try again. |
LIVE_VIDEO__DELETE_FAILED | Live Video Not Deleted | There was a problem and we were not able to delete your live video. Please try again. |
LIVE_VIDEO__EDIT_API_NOT_ALLOWED | Editing Via Video API Is Not Allowed While Live | Editing a live video using the Video Edit API is not allowed. Use the live video ID. |
LIVE_VIDEO__LIVE_STREAM_ERROR | Generic Stream | There was an error during the stream |
LIVE_VIDEO__NOT_EXIST | Live Video Does Not Exist | The live video you are trying to access does not exist in the system any more. |
LIVE_VIDEO__PRIVACY_REQUIRED | Privacy Setting Required | You need to set a privacy before going live. |