Getting Started

This document explains how to use the Live Video API to create a LiveVideo object, get a stream URL, and broadcast 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.

If you do not plan on building an app, use Facebook’s Live Video Publishing tool to broadcast live videos.

Before you Start

You will need access to the following:

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 platorm 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:

  • publish_video

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.

Once you have triggered the modal, click OK 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. Get a Stream URL

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. Change the operation method to POST and send a request to:

me/live_videos?status=LIVE_NOW

This will return a response that looks like this:

{ 
  "id": "{live-video-id}",
  "stream_url": "rtmp://rtmp-api.faceboo...",
  "secure_stream_url": "rtmps://rtmp-api.faceboo...",
  "stream_secondary_urls": [],
  "secure_stream_secondary_urls": []
}

Make a note of the id and stream_url rtmps values that were returned to you. You will need them to create and end your stream.

5. Stream to the URL

Capture the stream_url value that you received in the last step and pass the url to your encoding device. The encoding device will use the url as the ingest URL which you can use to start a stream.

Depending on which streaming software you are using, you may have to break the stream URL into its server (rtmp://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.

This will create a live video post on your User profile, but as long as your app is still in development mode, it will only be visible to you. View your profile and verify that a new live video post has been created and is receiving your stream data.

Once you are able to successfully stream to Facebook in development mode, you can submit your app for app review and switch to live mode.

6. End the Stream

Once you have verified that you are streaming to the live video post on your User profile, end the stream by sending a POST request to your live video's ID and include the end_live_video=true parameter in your request. For example, if your live

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

This ends your live video and saves it as a video on demand (VOD). If you want to delete it, change the operation method to DELETE and send the request to your live video ID.

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.