Graph API Version

Group Live Videos

For more information about the Live Video API, visit our Live Video Docs.

Creating

You can make a POST request to live_videos edge from the following paths:

  • /group_id/live_videos

When posting to this edge, a LiveVideo will be created.

Parameters

NameDescription
app_attribution_tag

numberic string or integer

An attribution tag for live videos which will show on feed.

attribution_app_id

numberic string or integer

Id of the attribution app.

content_tags

list<numberic string>

Tags that describe the contents of the video. Use search endpoint with type=adinterest to get possible IDs. Example query:

/search?type=adinterest&q=sunsets

description

UTF-8 string

The description of the live video. Supports Emojis.

encoding_settings

string

Identifier of the encoding settings group the broadcaster is using for this stream. This parameter is currently only in use for live-360 broadcasts. The value to be passed to this parameter is the value of the identifier key of the encoding settings preset. Encoding presets can be found by querying the /broadcaster_encoding_settings Graph API endpoint (GET query).

fisheye_video_cropped

boolean

Whether the single fisheye video is cropped or not.

front_z_rotation

float

The front z rotation in degrees on the single fisheye video.

game_id

numberic string or integer

Set which game this video is about. Use search endpoint with type=game to get possible IDs. Example query:

/search?type=game&=pubg

game_specs

Game Specs Parameter

Set metadata representing which game should be attributed.

is_spherical

boolean

Flag that denotes the broadcast is a 360 live broadcast.

live_encoders

list<numberic string or integer>

Live encoders that will broadcast to this live video.

original_fov

int64

Original field of view of the camera.

planned_start_time

integer

Unix timestamp when the broadcaster plans to go live.

post_surfaces_blacklist

list<enum{1, 2, 3, 4, 5}>

A blacklist of where the post won't show up, for feed only experience.

privacy

Privacy Parameter

Privacy for this live video.

projection

enum{EQUIRECTANGULAR, CUBEMAP}

Flag that denotes expected projection for 360 live streams. The default value is EQUIRECTANGULAR.

save_vod

boolean

Whether or not the video data should be saved for later consumption in VOD format. Default is true, except for certain broadcasts types (e.g. AMBIENT).

schedule_custom_profile_image

image

Custom image that will appear in the scheduled live story and lobby.

spatial_audio_format

enum{ambiX_4}

Denotes the format of the spatial audio stream. When unspecified audio is presumed to be mono or stereo.

status

enum {UNPUBLISHED, LIVE_NOW, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_CANCELED}

The status of the broadcast. A LIVE_NOW broadcast is currently live and visible to Users. An UNPUBLISHED broadcast is in preparation and not visible to other users. An unpublished broadcast may be automatically deleted after several hours in this state. Consider using the scheduled states to create a planned, future broadcast.

stereoscopic_mode

enum {MONO, LEFT_RIGHT, TOP_BOTTOM}

Set this flag to the stereoscopic mode for this video.

stop_on_delete_stream

Set this to true if the stream should be stopped when the deleteStream RTMP command is received.

stream_type

enum {REGULAR, AMBIENT}

The type of live video stream.

A REGULAR stream is subject to time limits and is a good match for most fixed duration live events, such as a baseball game. When a REGULAR stream ends a VOD (video-on-demand) is created (if save_vod is true). REGULAR is the default stream type.

An AMBIENT stream is not subject to time limits and is a good match for indefinite duration events, like panda cams. An AMBIENT stream ends when video is not received for several hours, and no VOD is generated.

title

UTF-8 string

The title of the live video. Supports Emojis.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {
  id: numeric string,
  stream_url: string,
  secure_stream_url: string,
  stream_secondary_urls: List [
    string
  ],
  secure_stream_secondary_urls: List [
    string
  ],
  dash_ingest_url: string,
}

Validation Rules

ErrorDescription

100

Invalid Parameter

200

Permissions error

Reading

Features

NameDescription

Groups API

This is a feature requiring App Review.

Example

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/your-group-id/live_videos",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
GET /v4.0/your-group-id/live_videos HTTP/1.1
Host: graph.facebook.com
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/your-group-id/live_videos"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
/* make the API call */
FB.api(
    "/your-group-id/live_videos",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/your-group-id/live_videos',
    'your-access-token'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

Learn more about the Graph API in our Using the Graph API Guide.

Parameters

NameDescription
broadcast_status

list<enum {UNPUBLISHED, LIVE, LIVE_STOPPED, PROCESSING, VOD, SCHEDULED_UNPUBLISHED, SCHEDULED_LIVE, SCHEDULED_EXPIRED, SCHEDULED_CANCELED}>

Allows you to specify what kind of live videos return. No value returns all status types.

source

enum{target, owner}

Default value: target

The source of where the videos should be queried. E.g target gets videos broadcast onto a group. Group Live Videos ONLY supports target.

Fields

Reading from this edge will return a JSON formatted result:

{
    "data": [],
    "paging": {}
}
data

A list of LiveVideo fields.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription

200

Permissions error

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.