The publish_actions permission has been deprecated. If your app has already been approved for this permission, you can continue using it to publish videos until August 1, 2018. To publish live videos to User timelines, Groups, or Pages after that date, request approval for the new publish_video permission instead.

Streaming Live Video with the Graph API

Facebook Live is a fun and powerful way to connect with your followers by creating rich stories on Facebook in real time. The Live API allows you to create stories on Facebook using live video content from a variety of sources. Go beyond mobile device cameras and bring in video from professional cameras, multi-camera setups and programmatic sources such as games or screencasts.

Before you begin, please read our platform policies. Note that Facebook's API should not be used to simultaneously stream content to other online services and that the API isn't intended for use with mobile phone cameras. Third-party ads should not be included in streams.

Device Registration and Pairing


Register the device, the encoder, to Go Live and the person using this device. Registering the encoder allows the Live API to automatically configure your encoder to the optimal settings for a Facebook Live broadcast. You no longer need to manually adjust the encoder settings to ensure the highest quality Live video. The Live API provides the ability to set preview, start, and stop modes for your encoder from the Facebook interface.

The encoder uses POST requests on /me/live_encoders that return the live_encoder_id. The live_encoder_id will then be used to perform POST requests. Register and associate an encoder with a user with these two steps.

  1. Pair a user and a device with a Facebook Oauth Access Token when a user logs into Facebook on their device
  2. Register and associate this encoder (device) with the user

The encoder only has to react and acknowledge these actions.

Device Pairing

Pre-requisites for the Encoder Developer:
  1. Create an App for your encoder in the App Dashboard.
  2. Add the Facebook Login product for Other platforms.
  3. Enable Login from Devices in Facebook Login > Settings.
  4. Get the App ID from the App Dashboard under Settings > Basic.
  5. Get the Client Token under Settings > Advanced.
On the Encoder:

The following steps must be taken if the device has never been paired, does not yet have an access token, or the access token has been rejected; expired, revoked, or the device has unpaired.

In the following requests ACCESS_TOKEN is APP_ID or CLIENT_TOKEN and the following required permissions are stored in SCOPE separated by commas:

  • publish_videos
  • publish_pages
  • manage_pages
  • publish_actions (see deprecation note below)

The publish_actions permission has been deprecated and is now reserved for apps that have been previously approved for its use. Use the new publish_video permission instead.

STEP 1. The encoder sends a request to Facebook for a VERIFICATION_URI and a USER_CODE:


The response from Facebook:

  "code": "92a2b2e351f2b0b3503b2de251132f47",
  "user_code": "A1NWZ9",
  "verification_uri": "",
  "expires_in": 420,
  "interval": 5

STEP 2. The encoder displays the USER_CODE on its display and asks the user to enter it on a VERIFICATION_URI page.

The encoder polls the device every INTERVAL seconds, waiting for the user to enter the USER_CODE in Facebook.


Facebook responds to the encoder polling on /device/login_status:

  "access_token": "ABCD...",
  "expires_in" : 5183996

Once the user has entered the USER_CODE, the encoder stores the ACCESS_TOKEN in a persistent file and is expected to renew the token before EXPIRES_IN seconds.

Encoder Registration

We now have a specific ACCESS_TOKEN and will use it in all the following API calls. Note, in the following example, the access_token and interval parameters will be ignored for the sake of simplicity.

STEP 1. The encoder generates and stores a random UUID to identify itself before being associated with a user. The UUID helps to not create multiple encoders for the same device. If the HTTP request fails it should retry and reuse the same UUID.

The encoder request:


Sample output using a Wowza ClearCaster:

  'name': 'encoder-1',
  'brand': 'Wowza',
  'model': 'ClearCaster',
  'version': '1.0',
  'device_id': UUID

STEP 2. The device_id does not exist, so Facebook creates a new Ent for it to get an FBID and stores the device_id.

Response to encoder:

'id': FBID

The encoder stores the FBID as live_encoder_id and can now do POST requests on /{live_encoder_id}.

Creating a Live Video

You can create a live video by making a POST request to the live_videos edge using the following paths:

  • /{user_id}/live_videos
  • /{page_id}/live_videos
  • /{group_id}/live_videos
  • /{event_id}/live_videos

If you're using the Graph API Explorer to make your POST requests, be sure to change your application name from Graph API Explorer to the name of your app.

Then check your access token to ensure you have requested either a user or page access token.

Next, make your POST request to the page, user, group, or event ID with the live_videos edge. This creates a live_video object which will return a video ID, an RTMP stream_url, and stream key. The server URL will be and the stream key will be everything after it. Use both in order to push video frames through your streaming software.

POST /{page_id}/live_videos

Put the RTMP stream URL into your encoder of choice. The example below is using Open Broadcasting Software, OBS, which can be downloaded for free. For OBS-specific broadcasts, click Settings then Stream and paste in your RTMP stream URL and key. Click Ok.

Be sure that your video sources are properly setup before you click Start Streaming. This will begin pushing video frames to the RTMP stream URL, which will cause them to appear live on Facebook.

To ensure premium quality live streams, please follow our technical specifications and streaming recommendations below:

Video Format:

  • We accept video in maximum 720p (1280x720) resolution at 30 frames per second, with 1 key frame every 2 seconds.
  • You must send an I-frame (keyframe) at least once every two seconds throughout the stream.
  • Recommended max bit rate is 4 Mbps. Going above this maximum is possible but will make live streams highly unstable.
  • Changing resolution midstream has negative impact on the broadcast.
  • Titles must be less than 255 characters otherwise the stream will fail.
  • The Live API accepts H264 encoded video and AAC encoded audio only.

Video Length:

  • 4 hour maximum length for live stream.
  • 4 hour maximum length for preview streams (either through Live dialog or publisher tools). After 240 minutes, a new stream key must be generated.
  • RTMP stream URLs will expire 24 hours after they are created.

Advanced Audio Settings:

  • Audio Sample Rate: 48 KHz
  • Audio Bitrate: 128 Kbps mono
  • Audio Codec: AAC

Advanced Video Settings:

  • Pixel Aspect Ratio: Square
  • Frame Types: Progressive Scan
  • Bitrate Encoding: CBR
  • Video Codec: H264

Playback of live content will only work if the input broadcast has both an audio and a video track.

Broadcasting a Live Video


Developers can indicate the exact frame and moment to go live creating seamless broadcasts. One great use case for this is to implement a countdown clock that signals the broadcaster the exact moment when a stream is live.

The Workflow Overview

  • Encoder starts in status ready
  • Encoder queries live_encoder_id with status=ready
  • If there is nothing to do right now FB responds with action=none and interval=X
  • Encoder sleeps X seconds and queries live_encoders with status=ready again
  • Facebook decides the encoder should execute ACTION and responds with action=ACTION
  • Encoder executes action ACTION
  • Encoder acknowledges action ACTION by querying live_encoders with status=ACTION

STEP 1. The user creates a new broadcast and selects an available encoder.

STEP 2. The encoder is idle in its polling loop on the {live_encoder_id} node. The request:

'status': 'ready'

STEP 3. Facebook asks the encoder to start capturing content on its input source. The response:

'action': 'capture', 'polling_interval': POLLING_INTERVAL,
'broadcast_id': BROADCAST_ID

STEP 4. The encoder starts capturing some content and collects the characteristics of its input source. The encoder request:

'status': 'capture',
'broadcast_id': BROADCAST_ID,
'cap_streaming_protocols': PROTOCOL,
'input_video_width': VIDEO_WIDTH,
'input_video_height': VIDEO_HEIGHT,
'input_audio_samplerate': AUDIO_SAMPLE_RATE,
'input_audio_channels': NUM_CHANNELS

STEP 5. Facebook sends the encoder the streaming url and encoding_settings. The encoding settings depend on the input_format, the encoding capabilities, and what Facebook supports. The response if h264 video codec was chosen:

'polling_interval': POLLING_INTERVAL,
'broadcast_id': BROADCAST_ID,
'streaming_protocol': PROTOCOL,
'video_bitrate': BITRATE,
'video_codec': VIDEO_CODEC,
'video_width': VIDEO_WIDTH,
'video_height': VIDEO_HEIGHT,
'video_h264_profile': H264_PROFILE,
'video_h264_level': H264_LEVEL,
'audio_bitrate': BITRATE,
'audio_channels': CHANNELS,
'audio_codec': AUDIO_CODEC,
'audio_samplerate': AUDIO_SAMPLE_RATE,
'streaming_url': RTMP_URL

STEP 6. Facebook waits to receive the RTMP stream from the encoder to display the preview.

STEP 7. The Encoder notifies Facebook that it is in preview status. The request:

'status': 'preview',
'broadcast_id': BROADCAST_ID

STEP 8. Facebook waits for the user to go Live. The response:

'action': 'none'

STEP 9. The user decides to go live. Facebook creates the post in the user's feed using the quick publish workflow.

The encoder request:

'status': 'preview',
'broadcast_id': BROADCAST_ID

The response:

'action': 'live',
'broadcast_id': BROADCAST_ID

STEP 9A. The encoder displays the countdown The request:

'status': 'live',
'broadcast_id': BROADCAST_ID

The response:

'action': 'none'

STEP 9B. Immediately after the countdown Facebook expects to see an RTMP AMF0 data onGoLive message that contains the timestamp value of the video frame to be publicly visible. It is mandatory to send this message or no video will be posted. If the encoder does not care about the first publicly visible frame, this timestamp can be set to 0. A wireshark decomposition of an example message is below. AMF0 Data message with OnGoLive string followed by an ECMA array with string timestamp and number that is the video frame timestamp value.

    Real Time Messaging Protocol (AMF0 Data onGoLive())
RTMP Header
01.. .... = Format: 1
..00 0101 = Chunk Stream ID: 5
Timestamp delta: 10948
Timestamp: 62719680 (calculated)
Body size: 39
Type ID: AMF0 Data (0x12)
String 'onGoLive'
AMF0 type: String (0x02)
String length: 8
String: onGoLive
ECMA array (1 items)
AMF0 type: ECMA array (0x08)
Array length: 0
Property 'timestamp' Number 90166
Name: timestamp
String length: 9
String: timestamp
Number 90166
AMF0 type: Number (0x00)
Number: 90166
End Of Object Marker

STEP 10. The user decides to end the live stream. The encoder request:

'status': 'live',
'broadcast_id': BROADCAST_ID

The response:

'action': 'ready'

STEP 11. The encoder stops the broadcast. The request:

'status': 'ready'

The response:

'action': 'none'

Reading a Live Video

Live API Reference

Issue a GET request to get information about the live video object.

For instance, you may wish to populate a live dashboard with current viewer count and total unique viewers. This can be accomplished by calling either:

GET /{live_video_id}?fields=live_views,total_views  
GET /{page_id}?fields=live_videos{live_views,total_views}

Note: After the live broadcast has finished, querying live_views will return 0.

Actions and Statuses

The encoder starts in the ready status.

Live Encoder Status FieldsDescription



The default status when it starts and is not doing anything


The encoder is capturing content from its input (SDI / HDMI)


The encoder is broadcasting its input to Facebook (eg: sending a RTMP stream to FB)


Same as preview but knowing that on Facebook side it is LIVE to the audience


Facebook API ActionsDescription


The device should start capturing video from its input


The device should start streaming its input to Facebook live server


The device should go live (eg: display count down)


The device should end whatever it is doing and go back to ready status


The device should do nothing (equivalent of NOOP). It is only useful in polling mode.

Encoding Settings Negotiation

On status=capture, the live encoder sends its capabilities and information about the source input. View the all source input parameters and return types.



Comma separated list of supported protocols. rtmp is not supported, please use rtmps

(e.g., rtmps)


Comma separated list of supported audio codecs

(e.g., aac)


Comma separated list of supported video codec

(e.g., h264)

Updating a Live Video

Live API Reference

You can update the properties of a live video by making a POST request. This includes some properties that may have been set at creation such as description.

POST /{live_video_id}?description="Testing Live Video"

Ending a Live Video

For instance, to trigger the end of a broadcast from the Graph API, rather than by sending an RTMP streamdelete message, you can update the POST request using the end_live_video parameter by setting it to true. This will stop the broadcast and is only valid if the live video is still running.

POST /{live_video_id}?end_live_video=true

Deleting a Live Video

Live API Reference

You can delete a live video by making a DELETE request.

DELETE /{live_video_id}

This will delete the entire live_video object, including the recorded video on demand and associated story.



Telemetry enables you to send Facebook diagnostic data to enable us to continually improve Facebook Live.

The device is expected to report its telemetry by doing POST requests on the /live_encoder_id>/telemetry edge every 30 seconds when it is in capture, preview, or live state. Common parameters of a telemetry event are listed below. For a complete list, please visit the Live Encoder API Reference docs.

  • broadcast_id
  • cpu_usage
  • framerate
  • frames_dropped
  • memory_usage
  • status
  • timestamp
  • network_latency
  • network_rx_bandwidth
  • network_rx_packets_dropped
  • network_rx_packets_errors
  • network_tx_bandwidth
  • network_tx_packets_dropped
  • network_tx_packets_errors

Viewer Experience

Once a live_video object is created and the frames have been pushed through your streaming software, the viewer will begin to see a live stream. In the top left corner, they will see how many people are watching the broadcast as well as determine how long the broadcast has been playing regardless of when they started watching.

As soon as the live video begins streaming, the viewer will receive a notification indicating that a profile or page they're following has gone live.

The viewer has the opportunity to follow the profile or page from within the comment stream.

They'll have the option to comment during the live stream as well as like others' comments.

Once you decide to end the live stream, the viewer will be presented with a screen that allows them to follow future live broadcasts, which will notify them the next time the profile or page goes live. The live video will then appear on the profile or page.

App Review

If your app allows Users to live stream videos to their timelines, Groups, or Pages, your app must undergo App Review. Request approval for the following features and permissions:



  • Publishing to User timelines: publish_videos
  • Publishing to Pages: manage_pages, publish_pages
  • Publishing to Groups: publish_to_groups

If you are posting to Pages, you should also request the pages_show_list permission in order to get a list of the Pages your current app user has a role on.

Business Verification

If you will be posting to Pages, you must undergo Business Verification.

Supplemental Terms

If you will be posting to Pages, you must agree to our Supplemental Terms.

App Review Not Required

Your app does not need to undergo App Review in the following scenarios:

  • Your app only uses the Go Live dialog
  • Your apps post to your own User timeline, Page, Group, or Event. This is because all features and permissions are granted to App admins by default.
  • Apps in development mode, getting and publishing VODs or live videos to Users who have an appropriate role on your app, or to Pages they are admins of.


You can test your app's settings and approved features and permissions by using the Graph API Explorer — just select your app from the Application menu and start making requests.