Console
Documentation/Private media

Private media

Upload attachments and retrieve short-lived download links.

Media requires configured private object storage. An unconfigured deployment returns storage_not_configured; it does not pretend that an upload succeeded.

Upload

ts
const file = new Blob([fileBytes], { type: 'image/jpeg' });
const uploaded = await client.media.upload('number_id', file, 'receipt.jpg');
python
uploaded = client.upload_media(
    'number_id', image_bytes,
    filename='receipt.jpg', content_type='image/jpeg',
)

The endpoint accepts multipart form data with number_id and file. The current platform limit is 16 MiB per upload and 5 MiB for images; supported content types are validated by the server. Meta may impose additional format-specific constraints.

A platform media record has its own ID. Live uploads also track the corresponding Meta media identifier. Do not substitute a platform ID into a raw Meta field without following the deployed API's messaging schema.

Download

ts
const download = await client.media.download('media_id');

Download links expire after five minutes. They are bearer links: share only with an authorized consumer and do not persist them as permanent public URLs. The original media record remains tenant-scoped.

Retention and failures

Content retention covers attachments as well as text. Interrupted or failed uploads remain discoverable for cleanup. A failed upload must not be presented as a ready attachment in the inbox.

Prepared 18 November 2026 · Sqkii Pte. Ltd.