Spaces:
Paused
Paused
| title: Telegram Bot API Proxy & Tools | |
| emoji: 🚀 | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| <!-- Navigation --> | |
| <p align="center"> | |
| <a href="#ru">Русский</a> • <a href="#en">English</a> | |
| </p> | |
| --- | |
| <a id="ru"></a> | |
| ## 🇷🇺 Прокси Telegram Bot API с расширенными инструментами | |
| Этот Space запускает локальный сервер Telegram Bot API (на основе официальной сборки TDLib) и предоставляет многофункциональное Node.js приложение-прокси с дополнительными инструментами для управления файлами и генерации ссылок. | |
| **Посетите корневой URL вашего Space для интерактивной документации по API.** | |
| ### 1. Конфигурация | |
| #### 1.1. Секреты (Обязательные и Опциональные) | |
| Эти переменные должны быть установлены как "Secrets" в настройках вашего Hugging Face Space (`Settings -> Secrets`). | |
| | Переменная | Обязательность | Описание | Пример значения | | |
| | :-------------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- | | |
| | `TELEGRAM_API_ID` | **Обязательно** | Ваш API ID, полученный от Telegram (my.telegram.org). | `1234567` | | |
| | `TELEGRAM_API_HASH` | **Обязательно** | Ваш API Hash, полученный от Telegram. | `0123456789abcdef0123456789abcdef` | | |
| | `GITHUB_TOKEN` | Опционально | Персональный токен доступа GitHub с правом `gist`. Необходим для автоматического обновления Gist с информацией о Space. | `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx` | | |
| | `ENV_GIST_ID` | Опционально | ID существующего GitHub Gist, в который будет записываться информация. Требуется, если указан `GITHUB_TOKEN`. | `abcdef0123456789abcdef0123456789` | | |
| | `LINK_ENCRYPTION_KEY` | Опционально | Секретная фраза для шифрования полезной нагрузки в ссылках `/downloadEncrypted`. Если не указана, генерация зашифрованных ссылок отключена. | `ОченьДлинныйИСлучайныйКлюч123!` | | |
| | `GITHUB_USERNAME` | Опционально | Ваш логин на GitHub. Используется для формирования ссылки на Gist. Если не указан, но `GITHUB_TOKEN` и `ENV_GIST_ID` есть, Gist все равно будет обновляться. | `ваш_логин_github` | | |
| #### 1.2. Переменные Окружения (Настраиваемые с Значениями по Умолчанию) | |
| Эти переменные можно переопределить, добавив их в "Secrets" вашего Space. Если они не переопределены, используются значения по умолчанию. | |
| | Переменная | По умолчанию | Описание | | |
| | :----------------------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | `INTERNAL_TELEGRAM_API_PORT` | `8081` | Внутренний порт, на котором запускается сам процесс `telegram-bot-api`. Node.js приложение проксирует запросы на этот порт. | | |
| | `TELEGRAM_DATA_DIR` | `/var/lib/telegram-bot-api` | Директория на сервере, где `telegram-bot-api` хранит свои данные, включая кэшированные файлы. | | |
| | `FILES_TTL` | `-1` | Время жизни (TTL) для файлов в кэше `TELEGRAM_DATA_DIR` в часах. Файлы старше этого времени будут периодически удаляться. Значение `-1` отключает автоматическую очистку. | | |
| | `PROXY_TELEGRAM_PATH_PREFIX` | `/tg` | URL-префикс, по которому будет доступен "чистый" прокси к Telegram Bot API. Например, `https://[SPACE_URL]/tg/bot<TOKEN>/METHOD`. | | |
| | `DEFAULT_LINK_EXPIRY_HOURS` | `24` | Время жизни по умолчанию в часах для генерируемых зашифрованных ссылок (через эндпоинт `/file/.../getFile` или при автоматическом расширении ответов). Значение `-1` означает бессрочные ссылки. | | |
| ### 2. Основные возможности и эндпоинты | |
| **Посетите корневой URL вашего Space (`https://[YOUR_SPACE_URL]/`) для интерактивной HTML-документации по всем эндпоинтам.** | |
| Ниже приведено краткое описание: | |
| #### 2.1. "Чистый" Прокси Telegram Bot API | |
| * **URL**: `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>` | |
| * **Описание**: Прямое проксирование запросов к вашему локальному экземпляру Telegram Bot API. Возвращает **неизмененный** ответ от API. Используйте этот эндпоинт, если вам нужен стандартный ответ API без каких-либо дополнений. | |
| #### 2.2. Расширенные Инструменты и Операции с Файлами | |
| ##### Базовый путь для файловых операций: `https://[YOUR_SPACE_URL]/file` | |
| 1. **Получение информации о файле с дополнительными ссылками:** | |
| * **Эндпоинт**: `GET /file/<YOUR_BOT_TOKEN>/getFile?file_id=<FILE_ID>` | |
| * **Описание**: Делает запрос к локальному Telegram API (`getFile`), получает стандартный ответ и **дополняет** его следующими полями: | |
| * `direct_download_link_by_path`: Прямая ссылка для скачивания файла по его относительному пути в кэше. | |
| * `direct_download_link_by_id`: Прямая ссылка для скачивания файла через эндпоинт `/downloadFile`. | |
| * `delete_link_by_path`: Ссылка для удаления файла по его относительному пути в кэше. | |
| * `delete_link_by_id`: Ссылка для удаления файла по его ID. | |
| * `encrypted_download_link_by_path` (если `LINK_ENCRYPTION_KEY` установлен): Зашифрованная ссылка на скачивание по пути с ограниченным сроком действия. | |
| * `encrypted_download_link_by_id` (если `LINK_ENCRYPTION_KEY` установлен): Зашифрованная ссылка на скачивание по ID с ограниченным сроком действия. | |
| * **Параметр `link_expiry_hours`**: Можно добавить к запросу (например, `?file_id=...&link_expiry_hours=2`), чтобы указать время жизни для генерируемых зашифрованных ссылок (в часах, `-1` для бессрочных). По умолчанию используется `DEFAULT_LINK_EXPIRY_HOURS`. | |
| 2. **Другие файловые операции**: | |
| * `GET /stats`: Статистика по файлам в `TELEGRAM_DATA_DIR`. | |
| * Опциональный query-параметр `run_ttl_now=true` для немедленного запуска очистки старых файлов. | |
| * `GET /list?token=<YOUR_BOT_TOKEN>`: Список файлов для указанного бота с размерами. | |
| * `GET /<YOUR_BOT_TOKEN>/downloadFile?file_id=<FILE_ID>`: Скачать файл по ID. | |
| * `GET /<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Скачать файл по его полному относительному пути в кэше (например, `/bot123:abc/photos/file_0.jpg`). | |
| * `GET /downloadEncrypted?payload=<ENCRYPTED_PAYLOAD>`: Скачать файл по зашифрованной полезной нагрузке (полученной из эндпоинта `getFile`). | |
| * `GET /deleteFile?file=<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Удалить файл по его полному относительному пути. | |
| * `GET /<YOUR_BOT_TOKEN>/deleteById?file_id=<FILE_ID>`: Удалить файл по ID. | |
| ### 3. Информация в Gist | |
| Если настроены `GITHUB_TOKEN` и `ENV_GIST_ID`, информация о вашем Space (включая полезные URL) будет автоматически обновляться в указанном GitHub Gist (в файле с именем `hf_space_telegram_bot_api_proxy_info.json`). | |
| ### 4. Важно о путях к файлам | |
| * Локальный `telegram-bot-api` обычно сохраняет файлы в подкаталоге, названном в честь токена бота (например, `/var/lib/telegram-bot-api/bot123:abc/...`). Файлы в этом кэше могут не иметь расширений или иметь числовые суффиксы. | |
| * Относительные пути, используемые в URL инструментов (например, для скачивания или удаления по пути), должны включать эту структуру каталога токена: `bot<TOKEN>/<category>/<filename_in_cache>`. | |
| * При скачивании файлов приложение пытается установить корректный `Content-Disposition` и `Content-Type` для лучшего взаимодействия с браузером. | |
| --- | |
| <br> | |
| <a id="en"></a> | |
| ## 🇬🇧 Telegram Bot API Proxy & Tools | |
| This Space runs a local Telegram Bot API server (based on the official TDLib build) and provides a feature-rich Node.js proxy application with additional tools for file management and link generation. | |
| **Visit the root URL of your Space for interactive API documentation.** | |
| ### 1. Configuration | |
| #### 1.1. Secrets (Required and Optional) | |
| These variables must be set as "Secrets" in your Hugging Face Space settings (`Settings -> Secrets`). | |
| | Variable | Requirement | Description | Example Value | | |
| | :-------------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- | | |
| | `TELEGRAM_API_ID` | **Required** | Your API ID obtained from Telegram (my.telegram.org). | `1234567` | | |
| | `TELEGRAM_API_HASH` | **Required** | Your API Hash obtained from Telegram. | `0123456789abcdef0123456789abcdef` | | |
| | `GITHUB_TOKEN` | Optional | GitHub Personal Access Token with `gist` scope. Needed for automatic Gist updates with Space information. | `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx` | | |
| | `ENV_GIST_ID` | Optional | ID of an existing GitHub Gist where information will be written. Required if `GITHUB_TOKEN` is provided. | `abcdef0123456789abcdef0123456789` | | |
| | `LINK_ENCRYPTION_KEY` | Optional | Secret passphrase for encrypting payloads in `/downloadEncrypted` links. If not set, encrypted link generation is disabled. | `AVeryLongAndRandomKey123!` | | |
| | `GITHUB_USERNAME` | Optional | Your GitHub username. Used for forming the Gist link. If not set, but `GITHUB_TOKEN` and `ENV_GIST_ID` are, Gist will still be updated. | `your_github_username` | | |
| #### 1.2. Environment Variables (Configurable with Defaults) | |
| These variables can be overridden by adding them to your Space "Secrets". If not overridden, default values are used. | |
| | Variable | Default Value | Description | | |
| | :----------------------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | `INTERNAL_TELEGRAM_API_PORT` | `8081` | The internal port on which the `telegram-bot-api` process itself runs. The Node.js application proxies requests to this port. | | |
| | `TELEGRAM_DATA_DIR` | `/var/lib/telegram-bot-api` | The directory on the server where `telegram-bot-api` stores its data, including cached files. | | |
| | `FILES_TTL` | `-1` | Time-to-live (TTL) for files in the `TELEGRAM_DATA_DIR` cache, in hours. Files older than this will be periodically deleted. A value of `-1` disables automatic cleanup. | | |
| | `PROXY_TELEGRAM_PATH_PREFIX` | `/tg` | The URL prefix where the "clean" proxy to the Telegram Bot API will be available. E.g., `https://[SPACE_URL]/tg/bot<TOKEN>/METHOD`. | | |
| | `DEFAULT_LINK_EXPIRY_HOURS` | `24` | Default lifetime in hours for generated encrypted links (via the `/file/.../getFile` endpoint or when auto-augmenting responses). A value of `-1` means links do not expire. | | |
| ### 2. Core Features & Endpoints | |
| **Visit the root URL of your Space (`https://[YOUR_SPACE_URL]/`) for interactive HTML documentation of all endpoints.** | |
| Below is a brief overview: | |
| #### 2.1. "Clean" Telegram Bot API Proxy | |
| * **URL**: `https://[YOUR_SPACE_URL]/tg/bot<YOUR_BOT_TOKEN>/<METHOD_NAME>` | |
| * **Description**: Directly proxies requests to your local Telegram Bot API instance. Returns the **unmodified** response from the API. Use this endpoint if you need the standard API response without any additions. | |
| #### 2.2. Enhanced Tools & File Operations | |
| ##### Base path for file operations: `https://[YOUR_SPACE_URL]/file` | |
| 1. **Get File Info with Augmented Links:** | |
| * **Endpoint**: `GET /file/<YOUR_BOT_TOKEN>/getFile?file_id=<FILE_ID>` | |
| * **Description**: Makes a request to the local Telegram API (`getFile`), gets the standard response, and then **augments** it with the following fields: | |
| * `direct_download_link_by_path`: Direct link to download the file by its relative path in the cache. | |
| * `direct_download_link_by_id`: Direct link to download the file via the `/downloadFile` endpoint. | |
| * `delete_link_by_path`: Link to delete the file by its relative path in the cache. | |
| * `delete_link_by_id`: Link to delete the file by its ID. | |
| * `encrypted_download_link_by_path` (if `LINK_ENCRYPTION_KEY` is set): Encrypted, time-limited download link by path. | |
| * `encrypted_download_link_by_id` (if `LINK_ENCRYPTION_KEY` is set): Encrypted, time-limited download link by ID. | |
| * **`link_expiry_hours` parameter**: Can be added to the request (e.g., `?file_id=...&link_expiry_hours=2`) to specify the lifetime for generated encrypted links (in hours, `-1` for indefinite). Defaults to `DEFAULT_LINK_EXPIRY_HOURS`. | |
| 2. **Other File Operations**: | |
| * `GET /stats`: Statistics for files in `TELEGRAM_DATA_DIR`. | |
| * Optional query parameter `run_ttl_now=true` to immediately trigger cleanup of old files. | |
| * `GET /list?token=<YOUR_BOT_TOKEN>`: List files for the specified bot with sizes. | |
| * `GET /<YOUR_BOT_TOKEN>/downloadFile?file_id=<FILE_ID>`: Download a file by its ID. | |
| * `GET /<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Download a file by its full relative path in the cache (e.g., `/bot123:abc/photos/file_0.jpg`). | |
| * `GET /downloadEncrypted?payload=<ENCRYPTED_PAYLOAD>`: Download a file using an encrypted payload (obtained from the `getFile` endpoint). | |
| * `GET /deleteFile?file=<RELATIVE_PATH_INCLUDING_BOT_TOKEN_DIR>`: Delete a file by its full relative path. | |
| * `GET /<YOUR_BOT_TOKEN>/deleteById?file_id=<FILE_ID>`: Delete a file by its ID. | |
| ### 3. Gist Information | |
| If `GITHUB_TOKEN` and `ENV_GIST_ID` are configured, information about your Space (including useful URLs) will be automatically updated in the specified GitHub Gist (in a file named `hf_space_telegram_bot_api_proxy_info.json`). | |
| ### 4. Important Notes on File Paths | |
| * The local `telegram-bot-api` typically saves files in a subdirectory named after the bot token (e.g., `/var/lib/telegram-bot-api/bot123:abc/...`). Files in this cache may not have extensions or may have numerical suffixes. | |
| * Relative paths used in tool URLs (e.g., for download or delete by path) must include this bot token directory structure: `bot<TOKEN>/<category>/<filename_in_cache>`. | |
| * When downloading files, the application attempts to set correct `Content-Disposition` and `Content-Type` headers for better browser interaction. |