Локальный Telegram Bot API server в Docker Compose: коротко и с данными

Конспект страницы: 6 разделов коротко, данные на 14 октября 2026 и ответы на 3 вопроса. Полный разбор с примерами: Локальный Telegram Bot API server в Docker Compose.

Коротко

Telegram Bot API server в Docker Compose поднимает на вашем сервере тот же API, что работает на api.telegram.org, только без его ограничений: в режиме --local бот отправляет файлы до 2000 МБ и скачивает без лимита. Официального образа нет, сервер собирают из исходников tdlib/telegram-bot-api, а для запуска нужны свои api_id и api_hash. Свой Bot API нужен ботам, которые работают с большими файлами или держат тяжёлый вебхук.

Конспект по разделам

Что даёт свой Telegram Bot API server

Telegram Bot API server это открытый код того самого сервера, к которому обращается любой бот. Запущенный у себя с флагом --local, он снимает ограничения облачного API: Telegram сам пишет, что обычным ботам хватает облачного API. Переезжать стоит, если бот пересылает видео, архивы и большие документы, а общие вопросы размещения разобраны на странице телеграм-бот на хостинге.

• скачивание файлов без лимита вместо 20 МБ и загрузка до 2000 МБ вместо 50 МБ;
• загрузка файлов по локальному пути, а getFile сразу отдаёт абсолютный путь к файлу на диске;
• вебхук по HTTP, на любой локальный IP и любой порт;
• max_webhook_connections до 100000 вместо 100.

Где взять api_id и api_hash для Bot API server

Это единственные обязательные параметры. Их получают на my.telegram.org в разделе API development tools под своим аккаунтом Telegram, порядок описан в документации Telegram «Obtaining api_id». Передаются они флагами --api-id и --api-hash или переменными окружения TELEGRAM_API_ID и TELEGRAM_API_HASH.

Telegram Bot API server в Docker Compose

Зависимости по README: OpenSSL, zlib, компилятор с C++17, gperf и CMake 3.10 и новее. Двухэтапный Dockerfile собирает сервер и оставляет в образе только готовую программу: В.env лежат TELEGRAM_API_ID и TELEGRAM_API_HASH. Собирать образ при каждом обновлении не обязательно: соберите его один раз и храните в реестре контейнеров.

Как переключить бота на локальный Bot API

Запросы идут в том же формате, меняется только адрес: вместо https://api.telegram.org/bot<токен>/getMe бот обращается к http://127.0.0.1:8081/bot<токен>/getMe. В aiogram и python-telegram-bot для этого есть настройка своего сервера API. Перед переключением вызовите logOut на облачном API: иначе Telegram не гарантирует, что все сообщения дойдут.

Вебхук через локальный Telegram Bot API

Облачный API шлёт вебхук только по HTTPS и только на порты 443, 80, 88 и 8443. Локальный сервер отправляет его по обычному HTTP на любой порт и локальный адрес, например http://127.0.0.1:8080/ или имя контейнера бота в сети Compose. Домен и сертификат для вебхука больше не нужны.

Запустите свой сервер за пару минут

Почасовая оплата: тестовый стенд на сутки стоит десятки рублей, а не месячный тариф.

• NVMe-диски и гарантированная доля процессора
• Root-доступ и любой софт, от Docker до игровых серверов
• Маркетплейс: 91 приложение в один клик
• Бесплатный перенос проекта силами специалистов

Вопросы и ответы

Есть ли официальный Docker-образ Telegram Bot API server?

В README tdlib описана только сборка из исходников через CMake и генератор инструкций для разных систем. Образы на Docker Hub собирает сообщество, проверяйте, из какого кода они сделаны.

Можно ли вернуть бота с локального Bot API обратно на api.telegram.org?

Да. Вызовите logOut на своём сервере и снова отправляйте запросы в облако. Если бот только что вышел из облачного API, войти туда снова получится через 10 минут.

На каком порту работает Telegram Bot API server?

По умолчанию на 8081, порт меняет флаг --http-port. Сервер принимает только HTTP, поэтому наружу его не открывают без прокси с TLS.