Advanced Uses

Audience Targeting

Include and exclude specific audiences from viewing your Live Video.

Create a Target Audience

Node

• live_video

Access Token

• A Page access token of an admin of the Page with the manage_pages, publish_pages, and publish_video permissions.
• A User access token of an admin of the Group with 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

• live_video

Access Token

• A Page access token of an admin of the Page with the manage_pages, publish_pages, and publish_video permissions.
• A User access token of an admin of the Group with publish_video permissions.

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

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

• /page-id/live_videos
• /group-id/live_videos

Access Token

• A Page access token of an admin of the Page with the manage_pages, publish_pages, and publish_video permissions.
• A User access token of an admin of the Group with publish_video 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

• /live_video

Access Token

• A Page access token of an admin of the Page with the manage_pages, publish_pages, and publish_video permissions.
• A User access token of an admin of the Group with publish_video 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
}

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

• The Facebook SDK for Javascript must be implemented in either a browser (website) or WebView (desktop app).

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>

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

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.