Telegram → S3 Uploader Bot

A simple, private Telegram bot that uploads files to any S3-compatible storage (AWS S3, Cloudflare R2, MinIO, etc.) and returns a temporary presigned download link.

This project is designed to be:

• Simple
• Safe by default
• Easy to deploy
• Easy to extend

---

✨ Features

• Upload files from Telegram to S3-compatible storage
• Supports documents, videos, audio, and photos
• Private bucket (no public access required)
• Temporary presigned download links
• User allowlist (private bot)
• Works on local machine, VPS, Docker, and Railway
• Clean, minimal codebase

---

📦 Supported Storage

This bot works with any S3-compatible provider, including:

• AWS S3
• Cloudflare R2
• MinIO (local NAS)
• Wasabi
• DigitalOcean Spaces
• Backblaze B2 (S3 API)

---

🔐 Security Model

• Files are uploaded to a private bucket
• Access is granted via temporary presigned URLs
• Links expire automatically
• Storage credentials are never exposed to users
• Bot usage can be restricted with an allowlist
• Local files are stored temporarily and cleaned up automatically

This bot is intended for private file upload and backup use cases.

---

🚀 Deployment

▶ Deploy on Railway

You can deploy this bot directly to Railway:

After deployment, set the required environment variables in the Railway dashboard.

When deployed on Railway, this template attaches a Railway Bucket by default. You can remove it and configure any other S3-compatible storage via environment variables.

---

▶ Run locally

Python 3.13 is supported. Python 3.11+ is recommended for widest compatibility.

1. Clone the repository

git clone https://github.com/BigDaddyAman/telegram-s3-uploader
cd telegram-s3-uploader

2. Create virtual environment

python3.13 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Configure environment

Copy .env.example to .env and fill in your values:

cp .env.example .env

5. Run the bot

python bot.py

---

▶ Run with Docker (build locally)

docker build -t telegram-s3-uploader .
docker run --env-file .env telegram-s3-uploader

---

⚙️ Environment Variables

Variable	Description
API_ID	Telegram API ID
API_HASH	Telegram API hash
BOT_TOKEN	Telegram bot token
ALLOWED_USERS	Allowed Telegram user IDs (comma-separated)
S3_ENDPOINT	Custom S3 endpoint (leave empty for AWS)
S3_REGION	S3 region (required for AWS)
S3_ACCESS_KEY	S3 access key
S3_SECRET_KEY	S3 secret key
S3_BUCKET	Bucket name
PRESIGNED_EXPIRE_SECONDS	Presigned link expiration time (seconds)
ENABLE_PRESIGNED_URL	Enable or disable presigned download links (true / false)

---

📁 File Storage Layout

Uploaded files are stored using a simple structure:

Files are downloaded to a temporary local directory and removed automatically after upload.

users/
└── <telegram_user_id>/
    └── YYYYMMDD_HHMMSS_filename.ext

This makes the storage easy to browse and suitable for backups.

---

🧭 Project Scope

This project is intentionally kept small and focused.

It is meant for:

• Personal backups
• Private file storage
• Archiving Telegram content you own or manage

Features related to public distribution, streaming, or content sharing are out of scope.

---

🤝 Contributing

Contributions are welcome!

Please see CONTRIBUTING.md for guidelines and project scope.

---

🔐 Security

If you discover a security issue, please follow the instructions in SECURITY.md.

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.