Файлы и media в приватном диалоге

Что получится

В этом туториале бот отправит документ в приватный диалог, повторно отправит его по file_id, получит метаданные через getFile и скачает расшифрованные байты обратно через локальный gateway.

Что понадобится

выполненный quickstart по созданию бота и запуску gateway;
gateway профиля telegram-v1-core-preview-4, доступный по адресу http://127.0.0.1:8081;
Python 3 и bot token в переменной SKREPA_BOT_TOKEN;
приватный диалог с ботом в клиенте Скрепы.

Проверьте gateway:

set -o pipefail
curl --fail-with-body -sS http://127.0.0.1:8081/healthz | jq .

Ответ должен содержать "status":"ok" и "profile":"telegram-v1-core-preview-4".

Запускаем media-бота

Создайте окружение и небольшой тестовый документ:

python3 -m venv .venv
.venv/bin/python -m pip install 'python-telegram-bot==22.8'
printf 'Файл из туториала Скрепы\n' > sample.txt

Сохраните как media_bot.py:

import os
from pathlib import Path

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes


async def media(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    message = update.effective_message

    sent = await message.reply_document(
        document=Path("sample.txt"),
        caption="Первая отправка: multipart upload",
    )
    file_id = sent.document.file_id

    await message.reply_document(
        document=file_id,
        caption="Вторая отправка: тот же file_id",
    )

    descriptor = await context.bot.get_file(file_id)
    await descriptor.download_to_drive("downloaded-sample.txt")
    await message.reply_text(f"Скачано {descriptor.file_size} байт")


application = (
    Application.builder()
    .token(os.environ["SKREPA_BOT_TOKEN"])
    .base_url("http://127.0.0.1:8081/bot")
    .base_file_url("http://127.0.0.1:8081/file/bot")
    .build()
)
application.add_handler(CommandHandler("media", media))
application.run_polling(allowed_updates=["message"])

Запустите:

.venv/bin/python media_bot.py

Суффиксы /bot и /file/bot обязательны: SDK сам добавляет token, имя метода и путь файла.

Действия в клиенте Скрепы

Откройте приватный диалог с ботом.
Отправьте /media.
Дождитесь двух документов и сообщения о числе скачанных байт.

Проверяем результат

Сравните исходный и скачанный документы:

cmp sample.txt downloaded-sample.txt
echo $?

Код 0 означает полное совпадение. Остановите процесс, снова запустите его с тем же state_dir gateway и повторите /media: сохранённые gateway связи file_id продолжают работать после рестарта.

Тем же способом доступны sendPhoto, sendAudio, sendVideo и sendVoice. В python-telegram-bot им соответствуют reply_photo, reply_audio, reply_video и reply_voice.

Типичные ошибки

401 Unauthorized: token отозван или в URL попало старое значение.
400 ... file_id: идентификатор получен другим ботом либо потерян постоянный state_dir gateway.
Ошибка скачивания при рабочем getFile: gateway не получил весь ciphertext или проверка целостности завершилась неудачно; частичный plaintext при этом не возвращается.
File too large: размер одного вложения превышает 50 МиБ.
Попытка передать https://... вместо файла: загрузка media по внешнему URL в текущем профиле отключена. Передайте локальный файл или известный file_id.

Границы поддержки

Этот сценарий охватывает photo, document, audio, video и voice в приватных E2E-диалогах. file_id является непрозрачной строкой: его нельзя разбирать или превращать в публичный CDN URL. Анимации, стикеры, media groups и streaming upload пока не входят в профиль.