Загрузка файлов и изображений в Mini App Telegram: ограничения и практические решения

Если вы разрабатываете Mini App для Telegram, вы уже знаете: загрузка файлов и изображений - это одна из самых частых задач. Но что если пользователь не может загрузить фото, или файл размером 5 МБ просто отказывается загружаться? Проблема не в коде. Проблема в ограничениях самой платформы.

Что реально можно загружать в Mini App Telegram

Telegram Mini Apps работают внутри приложения, а не как отдельные веб-сайты. Это значит, что они не имеют полного доступа к файловой системе пользователя. Все загрузки проходят через API Telegram, и он накладывает жесткие ограничения.

Для изображений: максимальный размер - 5 МБ. Это не 10 МБ, не 15 МБ. Именно 5. Если пользователь пытается загрузить фото с камеры телефона, сделанное в высоком разрешении, оно легко может превысить лимит. Особенно если это снимок в формате HEIC или RAW, который автоматически конвертируется в JPEG, но всё равно остаётся тяжёлым.

Для других файлов - документов, аудио, видео - лимит тоже 5 МБ. Это касается любых типов: PDF, ZIP, MP3, MOV. Даже если вы используете tg-web-app и метод WebApp.openFilePicker(), платформа не позволит загрузить файл больше 5 МБ. Никаких обходных путей. Никаких исключений.

Почему такие жёсткие ограничения?

Telegram не хочет, чтобы Mini Apps превратились в облачные хранилища. Это не Dropbox. Не Google Drive. Это лёгкие приложения, которые работают быстро, даже на слабых интернет-соединениях. Если бы каждый Mini App мог загружать 100 МБ файлы, серверы Telegram начали бы перегружаться. А пользователи с медленным интернетом - терять терпение.

Кроме того, Telegram не хранит загруженные файлы на своих серверах. Он передаёт их только в вашу облачную систему - через webhook или прямой POST-запрос. Это значит, что вы сами отвечаете за хранение, обработку и безопасность файлов. Telegram лишь выступает как мост.

Как обойти ограничение в 5 МБ

Вы не можете обойти ограничение - но вы можете его обойти умно.

• Сжимайте изображения на стороне клиента. Используйте библиотеки типа browser-image-compression или sharp.js (если работаете с Node.js). Уменьшайте качество до 70-80% и размер до 1024x1024 пикселей. Для большинства случаев - это идеально. Фото всё ещё выглядит чётко, а размер падает с 8 МБ до 1,2 МБ.
• Разбивайте большие файлы. Если пользователь хочет загрузить видео 20 МБ - разбейте его на части по 4 МБ. Отправляйте каждую часть отдельно. На вашем сервере соберите их обратно. Это требует дополнительной логики, но работает. Многие приложения для редактирования видео в Telegram уже так делают.
• Используйте прямую загрузку в S3 или Cloudinary. Не загружайте файл с телефона пользователя в Mini App, а затем в ваш сервер. Пусть он загружает файл напрямую в ваше облачное хранилище. Используйте временные подписанные URL. Telegram позволяет открывать внешние ссылки. Вы можете показать пользователю кнопку «Загрузить в облако» - и он сразу перейдёт в интерфейс S3 или Cloudinary, где лимиты в 5 МБ не действуют.

Как проверить, что файл подходит

Не ждите, пока пользователь нажмёт «Отправить» и получит ошибку. Проверяйте файл до загрузки.

В JavaScript это делается просто:

function isValidFile(file) {
  if (file.size > 5 * 1024 * 1024) {
    return false;
  }
  if (file.type.startsWith('image/')) {
    return true;
  }
  if (file.type === 'application/pdf' || file.type === 'application/zip') {
    return true;
  }
  return false;
}

Покажите пользователю предупреждение, если файл слишком большой. Например: «Это фото весит 7,2 МБ. Максимальный размер - 5 МБ. Попробуйте сжать его или выбрать другое». Это снижает количество ошибок и улучшает UX.

Что нельзя загружать вообще

Некоторые типы файлов Telegram блокирует даже на уровне API. Вот что точно не пройдёт:

• Исполняемые файлы: .exe, .apk, .dmg, .bat
• Файлы с вредоносными расширениями: .js, .vbs, .scr
• Файлы, содержащие вредоносные метаданные (например, изображения с внедрённым JavaScript)
• Файлы, которые Telegram распознаёт как спам: .zip с 5000 файлами, .pdf с встроенными ссылками на фишинговые сайты

Эти ограничения не зависят от размера. Даже 100 КБ .exe-файл не пройдёт. Telegram сканирует файлы на лету. Если вы пытаетесь загрузить что-то подозрительное - API вернёт ошибку 403 Forbidden, а не просто отклонит по размеру.

Какие форматы работают лучше всего

Не все форматы одинаково надёжны. Вот список того, что работает стабильно:

• Изображения: JPEG, PNG, WebP
• Документы: PDF, DOCX, TXT
• Аудио: MP3, AAC
• Видео: MP4 (H.264), MOV (если сжато)
• Архивы: ZIP (до 5 МБ)

Форматы вроде TIFF, BMP, AVI, FLAC - работают редко. Иногда - только на iOS, иногда - только на Android. Не полагайтесь на них. Если пользователь загружает TIFF - предложите ему конвертировать в JPEG.

Что делать, если файл уже загрузился, но не отображается

Если файл прошёл проверку, но не появляется в интерфейсе - это не баг вашего кода. Это баг кэширования.

Telegram Mini App кэширует загруженные файлы на устройстве пользователя. Иногда он показывает старую версию. Решение - добавить к URL временный параметр:

https://yourserver.com/image.jpg?cachebust=1740201234

Где cachebust - это timestamp. Это заставляет браузер загружать файл заново, а не брать его из кэша.

Также убедитесь, что вы не используете localStorage для хранения ссылок на файлы. Telegram не гарантирует, что эти данные сохранятся после перезагрузки приложения. Используйте sessionStorage или отправляйте файлы на сервер сразу.

Сравнение ограничений: Mini App vs. обычный Telegram

Как видите, Mini App - это не замена обычному чату. Это инструмент для быстрых, лёгких действий. Если вам нужно загрузить 100 МБ презентацию - отправьте её через обычный чат. А в Mini App пусть пользователь загружает аватар, скан чека или небольшой PDF.

Как тестировать загрузку на разных устройствах

Тестирование на эмуляторе - не гарантия. Разные телефоны по-разному обрабатывают файлы.

• iPhone с iOS 18: Автоматически конвертирует HEIC в JPEG, но сохраняет высокое качество. Файл может быть тяжелее, чем кажется.
• Android 14: Некоторые производители (Samsung, Xiaomi) добавляют метаданные к фото. Это увеличивает размер на 1-2 МБ.
• Telegram для Windows: При загрузке через десктоп-версию файлы иногда теряют расширение. Убедитесь, что вы проверяете не только размер, но и тип файла.

Совет: всегда тестируйте на реальных устройствах. Возьмите старый Android-телефон, загрузите туда Telegram и попробуйте загрузить файл размером 4,8 МБ. Если он не проходит - значит, где-то в цепочке есть скрытый баг.

Что будет, если превысить лимит

Если вы отправите файл больше 5 МБ - Telegram не отправит его. Он не выдаст ошибку в консоли. Он просто проигнорирует запрос. Ваш сервер не получит его. Пользователь увидит «Загрузка...» и ничего больше.

Это самая опасная ситуация. Пользователь думает, что файл загрузился. Вы думаете, что он не загрузился. Никто не знает, что случилось.

Решение: всегда возвращайте явный ответ от сервера. Например:

{
  "status": "error",
  "code": "FILE_TOO_LARGE",
  "message": "Файл превышает лимит в 5 МБ. Попробуйте сжать его или выбрать другое."
}

И обязательно покажите это сообщение пользователю. Не оставляйте его в тишине.

Загрузка файлов в Mini App Telegram - это не просто техническая задача. Это баланс между удобством и производительностью. Если вы игнорируете ограничения - вы рискуете потерять пользователей. Если вы их понимаете - вы создаёте быстрый, надёжный и удобный опыт. Не пытайтесь обойти правила. Используйте их как руководство.