Before you start
Ask the user to authorize your app withvault:write, which lets your app upload files. Use the returned token and select a linked account the user shared. Keep the original filename and file type, such as image/png.
Install the TypeScript SDK version 4. Create a client on your server:
Start an upload
Callclient.access.uploads.start() with the original filename, size, file type, and MD5 hash. The SDK’s md5Hex() calculates the hash from the file bytes. The example below includes all four values.
The response has one of two statuses:
Each part includes
partNumber, uploadUrl, and byteRange.start and byteRange.end. Include the last byte in each range. Use the returned URL for each part.
Upload the parts and finish
Add this code after the client setup in a TypeScript file. Run it with the PNG path as its first argument. SetACCESS_TOKEN and LINKED_ACCOUNT_ID in your environment. For another file type, change contentType to match, such as image/jpeg. The SDK starts and finalizes the upload. The PUT requests send the file bytes to the returned upload URLs.
PUT. Do not wrap them in JSON, base64, or multipart form data. Keep the same bearer token and linked account headers for the upload URLs.
Finalization is required even for single-part uploads. POST /v3/access/uploads/finalize accepts 1 to 10 uploadIds. Without Vault options, it returns { "uploadIds": [...] }. Use the completed upload reference in mediaItems when you create content.
Keep a reusable Vault ID
To save the file in the Vault, use these finalization options in place of the finalization call above. SetuploadId to the new upload’s ID. Do not finalize the same upload twice:
listId is optional. Saving an upload in the Vault uses a temporary scheduled message. Its response contains uploads, each with uploadId, mediaId, and media, plus optional listId and messageId. Save uploads[].mediaId to use the file again. Optional mediaIds can include up to 10 existing IDs when adding the finalized media to a Vault list.
To upload several files, send POST /v3/access/vault/uploads. Include details for 1 to 10 files in files, along with the required vaultUpload options. Read batch status with GET /v3/access/vault/uploads/:batchId. See the API reference for each file’s status fields.
Use the result
Use completed references in posts, messages, and mass messages. Stories accept exactly one non-GIF image. A temporary upload reference works for one successful post, message, or story. You can reuse numeric Vault IDs. See Media references.Recover from an interrupted upload
Save the start response and finish the upload beforeexpiresAt. If a part fails, retry the same bytes at the same part URL before the upload expires. If you do not know whether a post, message, or story was created, check for it before trying again. Follow the response’s recovery instructions.
At upload start, OFAuth checks the file hash and size for a matching Vault item. Use the returned parts and byte ranges for any new upload.