Uploading Media Files

Media never travels over the WebSocket. Upload the file over HTTPS first, then send the id you get back in a message.

💡 Every SDK ships a MediaTransfer helper that does the whole PUT for you. Reach for the raw HTTP below only if you need the query parameters or you are not using an SDK.

SDKs

SDK	Call
Java	`String fileId = MediaTransfer.uploadFile(token, "./upload/photo.jpg");`
JavaScript	`const fileId = MediaTransfer.uploadFile(token, "./upload/photo.jpg", uploadServerURL);`
Python	`file_id = MediaTransfer.upload_file(token, "./upload/photo.jpg", upload_server_url)`

Pass the returned id to sendPhoto, sendVideo, sendDocument, and so on.

Raw HTTP

PUT https://<nandboxMediaServer>:<port>/nandbox/upload/<FileName>

For example: https://w1.nandbox.net:8080/nandbox/upload/photo.jpg

Headers

Header	Value
`Content-Type`	The file's MIME type. Must be correct — the server classifies the media by it.
`X-Token`	Your bot token.

Query parameters

Parameter	Description
`p`	`1` makes the upload public and returns a download link.
`cache`	`1` returns `size`, `width`, `height`, and a thumbnail. Only meaningful when `p=1`.

Body

The raw binary content of the file.

Supported media types

The server decides what kind of media you uploaded from the Content-Type header.

Media Type	Content Type (MIME Type)
Text File	`text/plain`
Image	`image/jpeg`, `image/png`, `multipart/form-data`
GIF Image	`image/gif`
Audio	`audio/midi`, `audio/mp4`, `audio/mpeg`, `audio/ogg`, `audio/basic`
Video	`video/mp4`, `video/mpeg`, `video/ogg`
File (documents & archives)	`application/zip`, `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/x-tar`, `application/x-7z-compressed`, `application/x-zip-compressed`, `application/x-rar-compressed`, `application/vnd.android.package-archive`, `application/vnd.ms-excel`

multipart/form-data is treated as an image upload.

Example

Request

javascript
async function uploadMedia(file, token) {
  const url = 'https://<nandboxMediaServer>:<port>/nandbox/upload/' + file.name;
  const params = new URLSearchParams({ p: 1, cache: 1 });

  const response = await fetch(`${url}?${params}`, {
    method: 'PUT',
    headers: {
      'Content-Type': file.type,
      'X-Token': token
    },
    body: file
  });

  if (!response.ok) {
    throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
  }
  return (await response.json()).file;
}

python
import os
import requests


def upload_media(file_path, token, content_type="image/jpeg"):
    url = "https://<nandboxMediaServer>:<port>/nandbox/upload/" + os.path.basename(file_path)

    with open(file_path, "rb") as file:
        response = requests.put(
            url,
            params={"p": 1, "cache": 1},
            headers={"Content-Type": content_type, "X-Token": token},
            data=file,
        )

    response.raise_for_status()
    return response.json()["file"]

Response

🟢 200

json
{
  "file": "media_id"
}