Hugging Face's logo

Spaces:
WalleGriffkinder
/
tgapi
Paused

App Files Community
tgapi / README.md
WalleGriffkinder's picture
WalleGriffkinder
Update README.md
da6bb93 verified
preview code
|
raw
history blame contribute delete
19.5 kB
metadata
title: Telegram Bot API Proxy & Tools
emoji: 🚀
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

Русский • English

🇷🇺 Прокси 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 для лучшего взаимодействия с браузером.

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