To start a live video stream on a User profile, get a User access token with the publish_video
permission and send a POST
request to the /{user-id}/live_videos
edge and include the status=LIVE_NOW
parameter. You can use the title
and description
parameters to include a title and description.
Upon success, this endpoint will return a stream_url
, secure_stream_url
, and a LiveVideo
object id
. The live video will appear in a post on the User's profile as soon as you send data to one of its stream URLs. You can use the live video ID to monitor your stream health, to end the stream, and to delete the video.
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 start a live video stream on a Page, get a Page access token of an admin of the Page with the publish_video
and manage_pages
permissions. Then, send a POST
request to the /{page-id}/live_videos
edge and include the status=LIVE_NOW
parameter. You can use the title
and description
parameters to include a title and description.
Upon success, this endpoint will return a stream_url
, secure_stream_url
, and a LiveVideo
object id
. The live video will appear in a post on the Page as soon as you send data to one of its stream URLs. You can use the live video ID to monitor your stream health, to end the stream, and to delete the video.
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 start 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 start a live video stream 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 POST
request to the /{group-id}/live_videos
edge and include the status=LIVE_NOW
parameter. You can use the title
and description
parameters to include a title and description.
Upon success, this endpoint will return a stream_url
, secure_stream_url
, and a LiveVideo
object id
. The live video will appear in a post on the Group as soon as you send data to one of its stream URLs. You can use the live video ID to monitor your stream health, to end the stream, and to delete the video.
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=EAAC..."
{ "id": "1953020644813108", "stream_url": "rtmp://rtmp-api.facebook...", "secure_stream_url":"rtmps://rtmp-api.facebook..." }
You can read live streams to get their 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 get live video data, get an appropriate User or Page access token with the publish_video
permission, then send a GET
request to the /{live-video-id}
node and include the ingest_streams
field.
curl -i -X GET \
"https://graph.facebook.com/{live-video-id}
?fields=ingest_streams
&access_token=EAAC..."
{ "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 live stream, send a POST
request to the /{live-video-id}
node and include the end_live_video=true
parameter. This will set the LiveVideo
object's status to VOD
so that it can viewed on demand.
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=EAAC..."
{ "id": "10213570560993813" }
You can perform a GET
operation on the live video's ID to confirm that its status has been set to VOD
.
{ "title": "\"Today's Live Video\"", "status": "VOD", // Live video has ended and saved as a Video on Demand "stream_url": "rtmp://rtmp-api.facebook...", "secure_stream_url": "rtmps://rtmp-api.facebook...", "embed_html": "<iframe src=\"https://www.facebook.com/plugins/video.php?href=https%3A%2F%2Fwww.facebook.com%2Fuser.name%2Fvideos%2F10213570560993813%2F&width=0\" width=\"0\" height=\"0\" style=\"border:none;overflow:hidden\" scrolling=\"no\" frameborder=\"0\" allowTransparency=\"true\" allowFullScreen=\"true\"></iframe>", "id": "10213570560993813" }
To delete a live video or VOD, send a DELETE
request to the {live-video-id}
node.
curl -i -X DELETE \
"https://graph.facebook.com/{live-video-id}?access_token=EAAC..."
{ success: true }
Error messages are sent via RTMP then to the Graph API. You can use the broadcast-id or live-video-id and query the error codes. Errors returned will contain the error code, type, message, and a timestamp.
Send a GET /id/
request where id
is the live-video-id or the broadcast-id with the errors
field.
curl -i -X GET \
"https://graph.facebook.com/{your-live-video-id}
?fields=errors
&access_token={your-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. |