Getting Started

This document explains how to use the Live Video API to create a live video broadcast on your own User profile using your app. If you do not have an app, you can use the Graph API Explorer and free streaming software, such as OBS or Player.me.

Before You Start

You will need access to the following:

  • A Facebook Developer account
  • A registered Facebook App with Basic settings configured

If you don't have an app, you will also need:

1. Configure Facebook Login

Add the Facebook Login product to your app in the App Dashboard.

You can leave all settings on their defaults. If you are implementing Facebook Login manually (which we don't recommend), enter your redirect_uri in the Valid OAuth redirect URIs field. If you will be using one of our SDKs, you can leave it blank.

2. Implement Facebook Login

Follow our Facebook Login documentation for your platform and implement Facebook Login into your app. If your app is on a device that does not have an interface that allows users to sign into Facebook, implement Facebook Login for Devices instead.

Your app will need the following permissions:

If your app isn't ready yet and you're using the Graph API Explorer and streaming software, you can skip this step.

3. Get an Access Token

Once you've implemented Facebook Login, make sure you are signed into your Facebook Developer account, then access your app and trigger the Facebook Login modal. If you are using the Graph API Explorer, select your app from the Facebook App dropdown menu and click the Generate Access Token button.

Once you have triggered the modal, click the dropdown menu and select Only me so that you will be the only one who is able to see the broadcast. Click OK, and in the next modal click OK again to grant your app the publish_video permission. The API should return a User access token. Capture the token so your app can use it in the next few queries.

If you are using the Graph API Explorer, it will be captured automatically and displayed in the Access Token field for reference:

4. Create a LiveVideo Object

Now that you have an access token with the publish_video permission, you can use it to create a LiveVideo object on your User profile.

Send a request to the POST /me/live_videos?status=LIVE_NOW endpoint. For example:

curl -i -X POST \
 "https://graph.facebook.com/v3.3/me/live_videos?status=LIVE_NOW&access_token={access-token}"

This will return a response that looks like this:

{ 
  "id": "10214937378883406",  //The LiveVideo object ID
  "stream_url": "rtmp://rtmp-api.faceboo...",
  "secure_stream_url": "rtmps://rtmp-api.faceboo...", //The stream URL
  "stream_secondary_urls": [],
  "secure_stream_secondary_urls": []
}

Capture the id and secure_stream_url values that were returned to you. The id is the LiveVideo object ID, which you can use to manipulate your broadcast. The secure_stream_url is the ingest URL that you will use to stream live video data from your encoder to the LiveVideo object.

5. Stream to the Secure Stream URL

Pass the secure_stream_url value that you captured in the last step to your encoding device and stream live video data to it. Once the LiveVideo object detects streaming data, the broadcast will go live on your User profile.

View your profile and verify that a new live video post has been created and is broadcasting your streaming data.

If you are using streaming software instead of developing your own app, manually add the secure_stream_url value to your software. Depending on which streaming software you are using, you may have to break the stream URL into its server (rtmps://rtmp-api.facebook.com/rtmp/) and key components (everything after /rtmp/).

For example, in OBS, choose OBS > Preferences. This opens the Settings screen. Set the Service to Facebook Live, add the stream URL in Settings > Stream > Stream Key, then start your stream.

6. End the Broadcast

Once you have verified that you are broadcasting live video on profile, end the broadcast by sending a request to the POST /{live-video-id}?end_live_video=true endpoint. For example:

curl -i -X POST \
  "https://graph.facebook.com/v3.3/{live-video-id}?end_live_video=true&access_token={access-token}"

This ends your broadcast and saves it as a video on demand (VOD). If you want to delete the VOD, send a request to the DELETE /{live-video-id} endpoint.

Next Steps

Find more examples of using the Live Video API to schedule a live video, post to a Page or Group, and get User reactions and comments in Common Uses.