| --- |
| sdk: docker |
| app_port: 7860 |
| --- |
| |
| # TeleSave |
|
|
| TeleSave is an asynchronous Telegram download bot designed for Docker deployments on Hugging Face Spaces. It accepts public social-media URLs and direct HTTP/HTTPS file links, downloads the content, and sends it back through Telegram. |
|
|
| ## Features |
|
|
| - Async Telegram bot built with aiogram 3. |
| - Broad social/media support through yt-dlp. |
| - Direct HTTP/HTTPS streaming downloader for files. |
| - Bundled local Telegram Bot API server mode for uploads up to 2 GB. |
| - Automatic Telegram send method selection for photos, videos, audio, voice, albums, and documents. |
| - SSRF protection for direct download URLs. |
| - Configurable file-size, timeout, and concurrency limits. |
| - Health endpoint for Hugging Face Spaces at `/healthz`. |
| - Safe temporary work directories with cleanup after every job. |
|
|
| ## Deployment modes |
|
|
| ### Option A: hosted Telegram Bot API fallback |
|
|
| This is the simplest mode, but it does not provide reliable 2 GB uploads. |
|
|
| ```env |
| TELEGRAM_API_BASE_URL=https://api.telegram.org |
| TELEGRAM_LOCAL_MODE=false |
| ``` |
|
|
| ### Option B: local Telegram Bot API server |
|
|
| This is the recommended mode for uploads up to 2 GB. It requires a Telegram `api_id` and `api_hash` from <https://my.telegram.org>. |
|
|
| ```env |
| TELEGRAM_API_BASE_URL=http://127.0.0.1:8081 |
| TELEGRAM_LOCAL_MODE=true |
| TELEGRAM_API_ID=your-api-id |
| TELEGRAM_API_HASH=your-api-hash |
| ``` |
|
|
| The Docker image copies a ready-to-use `telegram-bot-api` binary from the `aiogram/telegram-bot-api` image instead of compiling TDLib from source. This keeps Hugging Face Spaces builds fast while preserving the original local Bot API functionality for uploads up to Telegram's 2 GB bot limit. |
|
|
| `docker/start.sh` starts the bundled local Bot API server automatically when `TELEGRAM_LOCAL_MODE=true` and `TELEGRAM_API_BASE_URL` points at `127.0.0.1` or `localhost`. For local development, `docker-compose.yml` can still run the bot and a separate local Bot API service. |
|
|
| For a public Hugging Face Space, never commit a real `.env` file. Add these values in **Settings → Variables and secrets → Secrets**: |
|
|
| ```env |
| BOT_TOKEN=your-bot-token-from-BotFather |
| TELEGRAM_API_ID=your-api-id |
| TELEGRAM_API_HASH=your-api-hash |
| ``` |
|
|
| The Docker image already sets these non-secret defaults: |
|
|
| ```env |
| TELEGRAM_API_BASE_URL=http://127.0.0.1:8081 |
| TELEGRAM_LOCAL_MODE=true |
| ``` |
|
|
| ## Local development |
|
|
| 1. Copy the example environment file: |
|
|
| ```bash |
| cp .env.example .env |
| ``` |
|
|
| 2. Fill in `BOT_TOKEN`. |
|
|
| 3. Run with the hosted Bot API fallback: |
|
|
| ```bash |
| pip install -e '.[dev]' |
| python -m telesave.main |
| ``` |
|
|
| 4. Or run the local Bot API stack: |
|
|
| ```bash |
| docker compose up --build |
| ``` |
|
|
| ## Environment variables |
|
|
| See `.env.example` for the complete list. |
|
|
| Important settings: |
|
|
| - `BOT_TOKEN`: Telegram bot token from BotFather. |
| - `TELEGRAM_API_BASE_URL`: Hosted or local Bot API base URL. |
| - `TELEGRAM_LOCAL_MODE`: Enables aiogram local-file optimizations. |
| - `MAX_FILE_SIZE_MB`: Application-level upload limit, max 2000. |
| - `MAX_CONCURRENT_DOWNLOADS`: Global concurrency limit. |
| - `MAX_CONCURRENT_DOWNLOADS_PER_USER`: Per-user concurrency limit. |
| - `YTDLP_COOKIES_FILE`: Optional cookies file for sites requiring authenticated public access. |
|
|
| ## Notes |
|
|
| Some platforms block automated downloads, require login cookies, or change frequently. TeleSave keeps provider support extensible by isolating download strategies behind a downloader router. |
|
|
