README.md

---
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.