Uploading Files to Facebook with Resumable Upload API

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

  • It is based on a resumable protocol and can resume an upload reliably and efficiently without re-uploading the entire file. This is useful for uploading large files (eg. videos and photos) under poor network conditions
  • It allows file data to be processed as soon as they are uploaded
  • It simplifies existing upload flow and is easier use

Required Knowledge

This document assumes that you know how to use Facebook's Graph API. To learn more about the Graph API, please see our guide on Using the Graph API. Requests must be made from a registered app.

This document also assumes you know the difference between HTTP requests and HTTP headers. Part of the API adds a parameter in the request, and another part adds it as an HTTP header. Please consult your runtime's documentation and HTTP libraries to understand how to set either types before making requests.

Permissions

All API calls must include an access token. No specific Facebook Login Permissions are required to use the file upload part of the API, but posts of photos or videos to a Facebook Page or person's Timeline require video and photo upload permissions. To learn more about permissions see our documentation on Facebook Login Permissions.

API Overview

In order to use this API, you should use the following flow:

  1. Make a POST to the Graph API endpoint /app/uploads to create an upload session. This will return 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 will also require 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. If you want to check on the status of an upload, you can make a GET request to /upload:{unique_identifier} and it will return information about the upload.
  4. Once you're finished uploading, use the file handler obtained from 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 covers each part of the API in detail.

Creating an upload session

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

The way to create a new upload session is making a POST call via the /app/uploads endpoint. The call will look something like this:

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

The call will return a value that includes the session ID that you should use in later calls (This is server generated and you should NEVER modify it):

{
"id": "upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI"
}

The parameters file_length and file_type 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.

Uploading File Data

Once you get the session ID, you can start uploading file data. You do this by making a POST call to an endpoint that is named based on the session ID that was returned via the method described in the previous section.

The file_offset parameter must be included as an HTTP header. It will not 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).

In addition, the access token must be included in an Authorization HTTP header. It will not work as a query parameter. Please 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.

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.

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"