Upload Files to Facebook

Facebook offers a Resumable Upload API to upload files and use the uploaded media in other API calls.

The API allows:

  • Uploading large files (for example, videos and photos) under poor network conditions by resuming an upload reliably and efficiently without re-uploading the entire file.
  • Processing of file data as soon as it is uploaded.

Before You Start

You will need:

  • A Facebook app
  • No special permissions are needed to upload files, however, to create a post, permissions will be required. Learn More.

Overview

To use this API, we recommend using the following flow:

  1. Make a POST to the Graph API endpoint /app/uploads to create an upload session. This returns an opaque and unique identifier you can use to upload a file.

  2. Make a POST request to the Graph API endpoint /upload:{unique_identifier}, where the {unique_identifier} is replaced by the value returned by the previous call to /app/uploads. This call also requires that you include a file type, a file length, and a zero-based file offset, as described below.

  3. Continue to make calls to the upload endpoint until your file is finished uploading. To check the status of an upload, make a GET request to /upload:{unique_identifier}.

  4. Once you're finished uploading, use the file handler obtained from the POST call in parts of Facebook's Graph API. For example, you can use it when posting a person's photo or a Page story.

API Details

This section outlines each part of the API process.

Create an Upload Session

The first step to upload a file is to create an upload session and obtain a session ID that will be used in each call as you upload the file or check status of the upload.

To create a new upload session, make a POST call via the /app/uploads endpoint.

The call will look similar to this:

POST /app/uploads?access_token={access_token}&file_length={your_file_length_in_bytes}&file_type=image/jpeg

The call returns a value that includes the session ID to use in later calls:

This is server-generated and you should never modify it.

{
"id": "upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI"
}
  • The file_length and file_type parameters should be in this call, but alternatively may be included when uploading the file data.

  • The file_length argument is an unsigned 64 bit integer.

  • The file_type argument depends on the intended use of the file, and must be a standard MIME type. Most common file types are supported on those endpoints (eg. image/jpeg, video/mp4, etc).

  • The file_name is optional.


Upload File Data

Once you get the session ID, you can start uploading file data: Make a POST call to a named endpoint, based on the session ID and was returned via the method described in the previous section.

The file_offset parameter must be included as an HTTP header. It cannot work as a query parameter.

file_offset is a zero-based offset in bytes to indicate where the upload should resume from. For a new upload session, it should be 0.

The access token must be included in an Authorization HTTP header. It cannot work as a query parameter.

See the example below and include the OAuth keyword before your access token.

POST /upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI HTTP/1.1
file_offset: 0
Authorization: OAuth {long access token}
Host: graph.facebook.com
Connection: close

The file data should be attached using standard multipart/form-data according to RFC 2388, which is supported by most HTTP libraries. For example:

curl --location --request POST 
'https://graph.facebook.com/v12.0/upload:MTphdHRhY2htZW50OjM1OWU5Y2JlLTk2OGItNDFiOC04MDM4LTUyODMxZGUwNzI0ZT9maWxlX3R5cGU9aW1hZ2UlMkZqcGVnJmZpbGVfbGVuZ3RoPTEzNTU5OA==?sig=ARb7RfCb8n0GUPTFfrY' 
  --header 'Authorization: OAuth {long access token}' 
  --header 'file_offset: 0'
  --header 'Host: graph.facebook.com'
  --header 'Connection: close'
  --header 'Content-Type: multipart/form-data' 
  --data-binary @/path_to_file.jpeg

If you did not specify file_type and file_length when creating upload session, you need to specify those as query parameters in this call.

When we're done with uploading the data, you'll get a file handle:

{"h":"2:c2FtcGxlLm1wNA==:image/jpeg:GKAj0gAUCZmJ1voFADip2iIAAAAAbugbAAAA:e:1472075513:ARZ_3ybzrQqEaluMUdI"}

This value can be used in place of an uploaded file for subsequent graph calls.


Query File Upload Status

You can query status of an upload session by making a GET call to an endpoint that is named based on the ID that was returned via the method described in the previous section.

Just like when uploading data, you must include the access token as an HTTP header.

For example:

GET /upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI HTTP/1.1
Authorization: OAuth {long access token}
Host: graph.facebook.com
Connection: close

The result will be a JSON-encoded ID and offset:

{ "id": "upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI", "file_offset": 0 }

file_offset - 1 is the number of bytes that are already uploaded to the server. In a resume case (eg. your previous upload failed due to connection issue), you should do another POST call and set file_offset to this value.


Uploading a Video

Apps are able to upload videos to the Graph API to post on behalf of Facebook Events, Groups, or Pages. Videos must be published to the graph-video.facebook.com instead of the usual Graph API url, graph.facebook.com. To provide a way for your app Users to share content to their Facebook Timeline, we encourage you to use our Sharing products instead.

The Edges

Access Tokens

For a Group:

  • User access token with user_events and publish_videos permissions to post to an Event. The person requesting the access token must be an admin of the Event.
  • User access token with publish_to_groups and publish_videos permissions to post to an Group. The person requesting the access token must be an admin of the Group.

For a Page:

Examples

Create a POST /id/videos request where id can be an event-id, group-id or page-id.

Sample Pseudo-Code Request

POST graph-video.facebook.com/id/videos
    ?source={/path/to/file}
    &access_token={access-token}

Sample Response

{
  "id": "{video-id}"
  "post_id": "{post-id}"
}

Page Thumbnails

Currently, the only supported use case is for creating a thumbnail when creating a page story.

To do this, you can specify the ID as part of the thumbnail parameter when creating a Page story via the /page/feed edge.

Here's an example of a curl command that creates a page story with a thumbnail:

curl -v -X POST \
-H "Authorization: OAuth {your access token}"
-F "type=image/jpeg" \
"https://graph.facebook.com/me/feed?thumbnail=2:c2FtcGxlLm1wNA==:image/jpeg:GKAj0gAUCZmJ1vodshkjsFADip2AAAbugbAAAA:e:1472075513:ARZ_3ybzrQqEaluMUdI&link=https://www.google.com/search?q=image"