Advanced Uses

Audience Targeting

Include and exclude specific audiences from viewing your Live Video.

Create a Target Audience

Node

Before You Start

For live videos on a Page, you will need:

For live videos in a Group, you will need:

  • A User access token requested by an admin of the Group
  • The publish_video permissions

Examples

Send a POST /id request where id is the live-video-id and set the targeting field and it's parameters.

curl -i -X POST \
  "https://graph.facebook.com/{your-live-video-id}
    ?targeting={age_min:17, geo_locations:{countries:["US","CA","MX"]}}
    &access_token={your-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-live-video-id}/",
  new JSONObject("{}"),
  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:@{ @"targeting": @"{age_min:17, geo_locations:{countries:["US","CA","MX"]}, excluded_zipcodes:{"key":"US:10001"}}",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-live-video-id}/',
  'POST',
  {"targeting":"{age_min:17, geo_locations:{countries:[\"US\",\"CA\",\"MX\"]}, excluded_zipcodes:{\"key\":\"US:10001\"}}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-live-video-id}/',
    array (
      'targeting' => '{age_min:17, geo_locations:{countries:["US","CA","MX"]}, excluded_zipcodes:{"key":"US:10001"}}'
    ),
    '{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

{
  "targeting": {
    "age_max": 65,
    "age_min": 17,
    "geo_locations": {
      "countries": [
        "US",
        "CA",
        "MX"
      ]
    }
  },
  "id": "{your-live-video-id}"   
}

Get Target Audience Information

Node

Before You Start

For live videos on a Page, you will need:

For live videos in a Group, you will need:

  • A User access token requested by an admin of the Group

Examples

Send a GET /id request where id is the live-video-id with the targeting field.

Sample Request

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{your-live-video-id}",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "targeting");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-live-video-id}"
           parameters:@{ @"fields": @"targeting",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-live-video-id}',
  'GET',
  {"fields":"targeting"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{your-live-video-id}',
    '{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();
curl -i -X GET \
  "https://graph.facebook.com/{your-live-video-id}
    ?fields=targeting&access_token={your-access-token}"

Sample Response

{
  "targeting": {
    "age_max": 65,
    "age_min": 17,
    "geo_locations": {
      "countries": [
        "US"
        "CA",
        "MX"
      ]
    }
  },
  "id": "{your-live-video-id}"       
}

Continuous Live

The Continuous Live feature has been deprecated. Please discontinue use of this feature and remove any related code from your app.

Continuous live video supports an unlimited live stream on Facebook. Some great use cases for continuous live include live feeds of aquariums, museums, and zoos.

Before streaming, please note:

  1. Continuous live will not generate a VOD.
  2. Continuous live sends push notifications to followers.
  3. If the broadcaster ends the live video, the post will be unpublished from the timeline, which means only the broadcast owner will see it.

Start A Continuous Live Video

Edges

Before You Start

For live videos on a Page, you will need:

For live videos in a Group, you will need:

  • A User access token requested by an admin of the Group
  • The publish_video permission
  • The publish_to_groups permissions

Examples

Send a POST /id/live_videos request where id is your group-id or page-id with the stream_type parameter set to AMBIENT.

curl -i -X POST \
 "https://graph.facebook.com/{your-page-id}/live_videos
   ?stream_type=AMBIENT
   &access_token={your-page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{your-page-id}/live_videos",
  new JSONObject("{\"stream_type\":\"AMBIENT\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{your-page-id}/live_videos"
           parameters:@{ @"stream_type": @"AMBIENT",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{your-page-id}/live_videos',
  'POST',
  {"stream_type":"AMBIENT"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{your-page-id}/live_videos',
    array (
      'stream_type' => 'AMBIENT'
    ),
    '{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": "{live-video-id}",
  "stream_url": "rtmp://rtmp-api-dev.facebook.com:80/rtmp/{live-video-id}?s_l=1&s_sw=0&s_vt=api_dev&a=AbxrzdR83iK_3b641ac",
  "secure_stream_url": "rtmps://rtmp-api-dev.facebook.com:443/rtmp/{live-video-id}?s_l=1&s_sw=0&s_vt=api_dev&a=AbxrzdR83iK_3b64FDg"
}

End a Continuous Live Video

Nodes

Before You Start

For live videos on a Page, you will need:

For live videos in a Group, you will need:

  • A User access token requested by an admin of the Group
  • The publish_video permission
  • The publish_to_groups permissions

Examples

Send a POST id request, where id is the live-video-id, with the end_live_video parameter set to true.

curl -i -X POST \
 "https://graph.facebook.com/{your-live-video-id}
   ?end_live_video=true
   &access_token={your-page-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-video-id}"    // Now a VOD video-id
}

Allow Crossposting

To crosspost a live video to another Page, you must first set up a crossposting relationship between the two Pages.

Send a Crossposting Request

Before You Start

You will need:

Send a POST request to the /{page-id} endpoint with the begin_crossposting_handshake parameter set to the Page which you are sending the request and allow_live to true.

curl -i -X POST "https://graph.facebook.com/{page-1-id}
   ?begin_crossposting_handshake=[{partner_page_id:{page-2-id},allow_live:true}]
   &access_token={page-1-access-token}"

On success, your app will receive the following response:

{
  "success": true
}

Set allow_live to false to send a request to create a crossposting relationship wherein a Page can crosspost live videos to your Page only after your admins or editors have approved the video.

Accept a Crossposting Request

Before You Start

You will need:

Send a POST request to the /{page-id} endpoint with the accept_crossposting_handshake parameter set to the Page who sent the request and allow_live to true.

curl -X POST "https://graph.facebook.com/{page-2-id}
    ?accept_crossposting_handshake=[{partner_page_id:{page-1-id}, allow_live:true}]
    &access_token={page-2-access-token}"

On success, your app will receive the following response:

{
  "success": true
}

To deny a request, set allow_live to false.

Get Pending Crossposting Statuses

Send a GET request to the {page-id}/crosspost_pending_approval_pages endpoint of the Page you have sent a crossposting request to but have not yet received a reply.

Sample Request

curl -X GET "https://graph.facebook.com/{page-id}/crosspost_pending_approval_pages
    &access_token={page-access-token}" 

On success, your app will receive the following response:

{
  "crosspost_pending_approval_pages": {
    "data": [
      {
        'name': '{Page Name}',
        'id': "{page-id}",
      }
    ]
  }
}

Go Live Dialog

We've created a plugin to make the process of Live API integration as easy as possible enabling you to authenticate with Facebook, preview your live stream, and describe your live stream through a pop-up window before going live. This dialog is best suited for those streaming from the client side. Backend integrations should continue to use the API directly.

Requirements

To initialize a pop-up window with controls that determine where to direct your POST response insert the following code.

<button id="liveButton">Create Live Stream To Facebook</button>
<script>
document.getElementById('liveButton').onclick = function() {
  FB.ui({
    display: 'popup',
    method: 'live_broadcast',
    phase: 'create',
}, function(response) {
    if (!response.id) {
      alert('dialog canceled');
      return;
    }
    alert('{your-stream-url}:' + response.secure_stream_url);
    FB.ui({
      display: 'popup',
      method: 'live_broadcast',
      phase: 'publish',
      broadcast_data: response,
    }, function(response) {
    alert("video status: \n" + response.status);
    });
  });
};
</script>
Parameters Value Description

display

popup, iframe

How the dialog is open in your web page.

phase

create, publish

Dialog in create phase allows you to get stream url to upload video; Dialog in publish phase will provide preview and go live button. required

broadcast_data

The response object returned from either API or create phase.

This parameter is required for publish phase.

In the Create phase pop-up window, choose the live stream destination which can be on any pages or groups you manage. The POST response will include the stream_url and secure_stream_url fields. Either one can be broken out into a server URL and stream key.

The server URL is the first half of the stream_url: rtmp://rtmp-api.facebook.com:80/rtmp/

The stream key is the latter half of the stream_url: 10153307708286557?ds=1&a=AdrRKk4mOaqPbQdxDuk

Response FieldPhaseDescription

id

create, publish

The ID of broadcast video.

stream_url

create

A rtmp url that contains stream server and stream key used to upload the live stream.

secure_stream_url

create

A rtmps url, the stream url with secure protocol.

status

publish

String value indicating the status of broadcast.

In our code snippet, we have an alert call with the stream_url. Your client should start streaming using stream_url. Soon after the stream starts, you will notice a preview of the broadcast appear in the publish phase pop-up window. The dialog enables users to choose privacy settings without adjusting the request's privacy parameter and to set the Live video description, title, and topic tags.

Note: If the publish pop-up window is Offline, ensure that your firewall is not blocking RTMP and that any Adblocker software on your browser is turned off.

When you click Go Live, the dialog will close and within a few seconds, the live stream play on the page or group, according to the chosen destination.

With the latest updates, released on Sept. 11, 2017, metadata is injected into the first frame of a live video with frame-accurate start times. Encoders can now implement a countdown to alert publishers to the exact start of the video. You can also start and stop the video from the Facebook interface.