Telegram getFile: как восстановить истёкшую ссылку на скачивание
Если ссылка на скачивание файла Telegram-бота истекла, снова вызовите getFile с file_id этого файла и используйте полученный file_path. Telegram гарантирует действие подготовленной ссылки не менее одного часа, а не бессрочно. file_unique_id для скачивания не подходит. Этот способ восстановления относится к официальному Bot API: временный URL вложения из унифицированного webhook подчиняется другому контракту.
Главное
- Получить сообщение с медиа — не значит сохранить содержимое файла.
- Храните идентификатор файла и контекст сообщения, а URL считайте временным адресом.
- Истёкшую ссылку Bot API обновляйте через
getFile, а не повторяйте запрос к старому URL бесконечно. - Не переносите срок действия и механизм обновления Telegram на вложения UnifyPort.
Что возвращает getFile и что нужно сохранять
В справочнике Telegram Bot API метод getFile описан как получение базовой информации о файле и подготовка к скачиванию. При успехе он возвращает объект File. Назначение идентификаторов различается:
| Значение | Назначение по документации | Рекомендуемое применение |
|---|---|---|
file_id | Скачать или повторно использовать файл | Хранить вместе с идентификатором принявшего бота для следующих вызовов getFile |
file_unique_id | Идентифицировать файл во времени и между ботами; не позволяет скачать или повторно использовать файл | Использовать для сопоставления, но не вместо идентификатора скачивания |
file_path | Путь для скачивания подготовленного файла | Брать из актуального ответа, не считать старый путь постоянным |
file_name, mime_type | Необязательные метаданные документа, заданные отправителем | Сохранять из входящего сообщения при наличии и проверять перед использованием |
Сохраняйте также идентификаторы исходного чата и сообщения. Идентичность файла не означает право доступа к переписке: появление того же медиа в другом чате не должно автоматически открывать ему доступ к сохранённой копии.
Это поля Bot API, а не расширение схемы событий UnifyPort. Если способ подключения ещё не выбран, начните со сравнения Bot API webhook и унифицированного входящего webhook.
Как диагностировать ошибку скачивания Telegram-файла
Выбирайте восстановление по этапу, на котором произошёл сбой. Наличие миниатюры в интерфейсе не доказывает, что файл сохранён.
| Наблюдение | Что проверить | Граница восстановления |
|---|---|---|
getFile завершился ошибкой | Учётные данные бота, фактический file_id, ответ с ошибкой, размер файла | Сначала исправить запрос или выбрать поддерживаемый способ скачивания |
| Работавшая ссылка перестала открываться | Новый результат getFile | Повторить скачивание с новым адресом; не любая HTTP-ошибка означает истечение срока |
| Скачивание прерывается по таймауту | Сеть, таймаут обработчика, доступность хранилища | Ограничить повторы; при подозрении на истечение срока получить новый адрес |
| Файл скачан, но разбор не удался | Фактическое содержимое и поддержка формата парсером | Обновление ссылки не исправит неподдерживаемое или некорректное содержимое |
| Webhook получен, но собственной копии нет | Сохранённое задание и результат обработчика | Приём события и сохранение файла — разные этапы |
Сейчас справочник API и Bots FAQ указывают лимит скачивания 20 MB для Bot API, размещённого у Telegram. Не путайте его с лимитами загрузки или возможностями всех клиентов Telegram. Справочник отдельно описывает скачивание без этого ограничения при работе с локальным сервером Bot API. Это выбор инфраструктуры, а не параметр, позволяющий размещённому у Telegram endpoint принять файл большего размера.
Гарантия «не менее часа» не требует ждать час и не означает, что каждая ссылка перестанет работать ровно через час. Документированный способ получить новую ссылку после истечения срока — повторный вызов getFile.
Сохраняйте файлы после надёжного приёма событий
Ниже — рекомендуемая архитектура приложения, а не гарантия доставки со стороны Telegram:
- Сохраните полученное обновление и метаданные, достаточные для создания задания на скачивание. Зафиксируйте задание в постоянном хранилище до подтверждения приёма.
- Пусть обработчик получает адрес непосредственно перед скачиванием. Не заполняйте длинную очередь URL, срок действия которых уже идёт.
- Передавайте поток в закрытое временное хранилище, установив собственные ограничения размера и времени. Имя файла и MIME-тип от отправителя считайте недоверенными метаданными.
- Публикуйте ссылку на собственное хранилище только после скачивания и проверки содержимого. Не передавайте незавершённые файлы в интерфейс поддержки или обработку ИИ.
- При сбое сохраняйте причину без секретных данных и решение об ограниченном повторе. Если восстановление невозможно, показывайте состояние «вложение недоступно», а не «сообщение не получено».
Используйте имя файла или ключ объекта, сформированный приложением, а не пользовательский путь. Ограничивайте сетевые адреса, доступные обработчику; не пересылайте служебные учётные данные произвольным хостам; не записывайте секреты и подписанные URL в общие журналы. Успешная проверка подписи события не доказывает безопасность вложенного документа.
Проверьте отложенное задание, истёкший адрес, слишком большой файл, отсутствие необязательного имени и остановку обработчика во время записи. Критерий успеха — не просто успешный HTTP-запрос: нужная авторизованная переписка должна получить пригодную копию либо явное состояние ошибки. Это предлагаемые проверки, а не отчёт о проведённых тестах.
У медиа UnifyPort другой контракт восстановления
Неофициальный интерфейс UnifyPort доставляет нормализованные события message.received для подключённых аккаунтов обмена сообщениями. В справочнике стандартных событий описаны data.message.attachments[] и временные подписанные URL OSS. Руководство по полям медиа Telegram объясняет схему вложений; эта статья посвящена доступности файла после создания задания.
Для этого пути:
- Проверяйте подпись и надёжно сохраняйте событие согласно справочнику доставки webhook, затем своевременно обрабатывайте доступные URL в рамках своей политики хранения.
- Явно обрабатывайте отсутствие URL. Документированное представление слишком большого файла использует
attachments[].metadata.is_big_fileбезurl; не конструируйте адрес из идентификатора сообщения. - Не предполагайте, что нормализованное вложение содержит Bot API
file_id, и не передавайте его URL вgetFile. - Не переносите гарантию одного часа или лимит 20 MB из Bot API в настройки обработчика как свойства UnifyPort.
Публичный справочник UnifyPort не описывает endpoint обновления URL вложения. В нём также указано, что REST API чтения истории сообщений и гарантированного воспроизведения пропущенных payload нет. Если URL больше не работает, а собственной копии нет, не обещайте восстановление через переподключение аккаунта. Зафиксируйте ограничение и при необходимости организуйте повторную отправку с надлежащим разрешением или ручное сопровождение.
Частые вопросы
Можно передать file_unique_id в getFile?
Нет. Telegram прямо указывает, что этот идентификатор не подходит для скачивания или повторного использования. Для скачивания сохраняйте file_id.
Ссылка истекает ровно через час?
Не обязательно. Telegram гарантирует действие не менее часа. После истечения срока запросите новую ссылку через getFile.
Нужно ли передавать исходный URL браузеру или сервису ИИ?
Предпочтительнее скачать файл на сервере и предоставить ссылку на хранилище с проверкой прав доступа в приложении. Не раскрывайте учётные данные и не распространяйте временные подписанные URL только ради отображения вложения.
Может getFile обновить URL вложения UnifyPort?
Такое взаимодействие не документировано. Следуйте контракту каждого интерфейса и не придумывайте операцию обновления.
Следующий шаг и источники
Изучите контракт стандартных webhook-событий и добавьте явные состояния успешного и неудачного сохранения файла до подключения последующей автоматизации.
Источники проверены 2026-09-24:
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.