Resumable Upload API

1. 1

   Open a session on your app

   POST /{APP_ID}/uploads?file_name=…&file_length=…&file_type=image/jpeg, sent with your access token, returns {"id": "upload:<SESSION_ID>"}.

2. 2

   Send the bytes

   Call POST /upload:<SESSION_ID> with the headers Authorization: OAuth {ACCESS_TOKEN} and file_offset: 0, and the raw file as the body.

3. 3

   Keep the handle

   The response {"h": "…"} is the file handle. Store it with the template draft that will use it.

4. 4

   Resume if interrupted

   GET /upload:<SESSION_ID> returns file_offset. POST the remaining bytes from that offset instead of starting over.

5. 5

   Reference the handle

   Put it in the template's header component as example.header_handle, or in profile_picture_handle when you update the business profile.

Start

POST /{APP_ID}/uploads (file_name, file_length, file_type)

Upload

POST /upload:{SESSION_ID} with a file_offset header

Auth header

Authorization: OAuth {ACCESS_TOKEN}

Token type

A user access token, per Meta's upload guide

Returns

{"h": "<FILE_HANDLE>"}

Resume

GET /upload:{SESSION_ID} → file_offset

File types

PDF, JPEG/JPG, PNG, MP4

Used for

Template header_handle, profile_picture_handle

• Using a media ID as a header sample

  IDs from /{PHONE_NUMBER_ID}/media are for sending messages. Template creation needs a handle from this flow in example.header_handle.

• Sending the token with the Bearer scheme

  Meta's docs specify Authorization: OAuth {ACCESS_TOKEN} for the upload step, and say the call fails without the token in the header. Copy that format exactly.

• Declaring the wrong length or type

  The session is opened for a declared size and MIME type. Take file_length from the file's actual size in bytes and match file_type to its real content, or the upload will not complete cleanly.

• Restarting instead of resuming

  Re-uploading a large video from byte zero after a timeout wastes time and bandwidth. Read file_offset from the session and send only what is missing.

Creating a template with a media header fails without a valid sample handle. Teams that automate template management at scale, with dozens of festive variants or regional language versions, go through this flow constantly. Understanding it avoids the classic dead ends: using a media ID where a handle is required, sending the token with the wrong scheme, or re-uploading a large video from scratch after a dropped connection instead of resuming.

• Store each handle with the template draft it belongs to, so a rejected template can be fixed and resubmitted without hunting for the file.
• Check size and type locally against the header's media limits before opening a session.
• Log session IDs, because they are what you need to resume.
• Make sample media representative, since reviewers judge the template with it.