Getting Started

Follow these steps to get your app to stream a live video to Facebook while in development mode. 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.

If your app is still in development but isn't ready for streaming, you can follow our tutorial to stream with the Graph API Explorer.

To stream a live video to Facebook:

Note: If your Page is associated with a Business Manager account, you will need to use the Publisher Tools UI to post a live video.

Register Your App

Register your app in your app dashboard and copy your app ID, which you will need to make API requests.

Implement Facebook Login

Refer to our Facebook Login documentation to install an SDK and implement Facebook Login into your app. Facebook Login allows your app's users to authenticate and grant your app permission (in the form of access tokens) to access their data on Facebook. 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 from your app's users, depending on where you will be streaming:

  • publish_video, if you will be streaming on a User profile
  • publish_pages and manage_pages, if you will be streaming on a Page
  • publish_video and publish_to_groups, if you will be streaming on a Group

The instructions in this document assume your app will be publishing to a User profile.

Get an Access Token

Once you've implemented Facebook Login, your app Users can use it to grant your app the publish_video permission. If an app user grants your app permission, the API will respond with an access token, which you can capture using an SDK method.

Sample Code

LoginManager.getInstance().logInWithPublishPermissions(
    fragmentOrActivity,
    Arrays.asList("publish_video"));
FBSDKLoginManager *loginManager = [[FBSDKLoginManager alloc] init];
  [loginManager logInWithPublishPermissions:@[@"publish_video"]
                         fromViewController:self
                                    handler:^(FBSDKLoginManagerLoginResult *result, NSError
FB.login(function(response) {
  console.log(response);
}, {scope: 'publish_video'});

If you want to confirm that the User has granted your app the publish_video permission, you can perform a GET operation on the /{user-id}/permissions edge. Assuming the User granted the permission, the API response would look like this:

Sample Response

{
  "data": [
    {
      "permission":"publish_video",
      "status":"granted"
    }
  ]
}

Start a Live Video

Now that you have an access token with the publish_video permission, you can use it to create a live video on the User's timeline.

From your app, send a POST request to the /{user-id}/live_videos edge and include the status=LIVE_NOW parameter. This will create a Live Video object on the User and the API will return the object's stream_url and secure_stream_url RTMP values. Use these values to stream to the Live Video object. Once it receives your streaming data, the Live Video will appear in the User's timeline.

The response also includes the live video's id, which you can use to get stream data and to end the live video.

Sample Request

curl -i -X POST \
  "https://graph.facebook.com/{your-user-id}/live_videos
    ?status=LIVE_NOW
    &title="Today's Live Video"
    &description="This is the live video for today."
    &access_token={your-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-user-id}/live_videos",
  new JSONObject("{\"title\":\"Today's Live Video\",\"description\":\"This is the live video for today.\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-user-id}/live_videos"
           parameters:@{ @"status": @"LIVE_NOW",@"title": @""Today's Live Video"",@"description": @""This is the live video for today."",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-user-id}/live_videos',
  'POST',
  {"status":"LIVE_NOW","title":"\"Today's Live Video\"","description":"\"This is the live video for today.\""},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-user-id}/live_videos',
    array (
      'status' => 'LIVE_NOW',
      'title' => '"Today's Live Video"',
      'description' => '"This is the live video for today."'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{your-live-video-id}",
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

End the Live Video

To end the live video, send a POST request to /{live-video-id} node and include the end_live_video=true parameter. This sets the live video's status to VOD, so it can be viewed on demand.

Although you can end a live video by sending an RTMP "end-stream" command, we recommend that you explicitly end live videos via the API.

Sample Request

curl -i -X POST \
  "https://graph.facebook.com/{your-live-video-id}
    ?end_live_video=true
    &access_token={your-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-live-video-id}",
  new JSONObject("{\"end_live_video\":\"true\"}\"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-live-video-id}"
           parameters:@{ @"end_live_video": @"true",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-live-video-id}',
  'POST',
  {"end_live_video":"true"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-live-video-id}',
    array (
      'end_live_video' => 'true'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "id": "{your-live-video-id}"  // Now a VOD
}

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.