Skip to main content

Start a PDF upload

POST 

/api/v1/media/upload-start

Get a media ID for a PDF. You then use the ID in Send RCS as document.mediaId, instead of sending the file again. A PDF is uploaded in three steps, because the file itself doesn't go through this API:

  1. Start the upload. Call this endpoint with mimeType (application/pdf) and the exact size of the file in bytes. The answer has an uploadId, an uploadUrl and the uploadHeaders to use.
  2. Send the file. PUT exactly size bytes to uploadUrl, with the headers from uploadHeaders. Do it before uploadExpiresAt: the address works for 15 minutes.
  3. Complete the upload. Call Complete a PDF upload with the uploadId, before completeBy: you have 1 hour from the start. The answer has the mediaId.

Use the mediaId in Send RCS as document.mediaId. It lasts 24 hours from the start call, just like the media ID of an image, and you can use it as many times as you like until then.

The uploadUrl works like a password for 15 minutes. Don't log it or share it.

The same three limits per account as for Upload media apply, and a refused call starts nothing. For a PDF:

  • Uploads per hour counts every upload you start, finished or not.
  • Uploads at once counts an upload from the start until it is completed or refused, or until an hour has passed. Five unfinished starts therefore block a sixth for up to an hour.
  • Storage counts the PDFs and images that are stored and haven't expired, plus the size you declare. Uploads you haven't completed yet don't use storage.

A refused call answers 429 with a Retry-After header, except when the limit for your account is 0, which refuses every upload and sends no Retry-After. A storage refusal answers 400.

There is no test mode for PDF uploads. Leave testMode out, or set it to false.

Like Send RCS, the call needs RCS enabled for your account and an approved RCS sender: contact support.

Request​

Bodyrequired

The type and exact size of the PDF.

    mimeTypestringrequired

    The type of the file. Has to be application/pdf.

    Possible values: [application/pdf]

    sizeintegerrequired

    The exact size of the file in bytes, as a whole number from 1 to 52428800 (50 MB). A number sent as text, such as "1000", is refused.

    Possible values: >= 1 and <= 52428800

    testModeboolean

    There is no test mode for PDF uploads. Leave it out, or set it to false.

Responses​

The upload was started. Send the file to uploadUrl before uploadExpiresAt, then complete the upload before completeBy.