Локальный 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.
Ответ за 30 секунд
Свой Bot API нужен ботам, которые работают с большими файлами или держат тяжёлый вебхук. Соберите его из исходников в Docker, запустите с --local, не открывайте порт 8081 в интернет: сервер принимает только HTTP и сам не шифрует трафик.
VPS с NVMe-диском: бот и свой Bot API на одной машине, файлы читаются прямо с диска.
Как переключить бота на локальный Bot API8081порт по умолчанию
2000 МБпредел загрузки файла
10 минутнельзя вернуться в облако после logOut
01 · 1 мин
Что даёт свой Telegram Bot API server#
Telegram Bot API server это открытый код того самого сервера, к которому обращается любой бот. Запущенный у себя с флагом --local, он снимает ограничения облачного API:
- скачивание файлов без лимита вместо 20 МБ и загрузка до 2000 МБ вместо 50 МБ;
- загрузка файлов по локальному пути, а getFile сразу отдаёт абсолютный путь к файлу на диске;
- вебхук по HTTP, на любой локальный IP и любой порт;
- max_webhook_connections до 100000 вместо 100.
Telegram сам пишет, что обычным ботам хватает облачного API. Переезжать стоит, если бот пересылает видео, архивы и большие документы, а общие вопросы размещения разобраны на странице телеграм-бот на хостинге. Код сервера открыт под Boost Software License.
02 · 1 мин
Где взять 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.
Пара привязана к вашему аккаунту, поэтому храните её как пароль: в файле .env с правами 600, вне репозитория.
03 · 1 мин
Telegram Bot API server в Docker Compose#
Зависимости по README: OpenSSL, zlib, компилятор с C++17, gperf и CMake 3.10 и новее. Двухэтапный Dockerfile собирает сервер и оставляет в образе только готовую программу:
FROM debian:12 AS build
RUN apt-get update && apt-get install -y git cmake g++ gperf make zlib1g-dev libssl-dev
RUN git clone --recursive https://github.com/tdlib/telegram-bot-api.git /src
WORKDIR /src/build
RUN cmake -DCMAKE_BUILD_TYPE=Release .. && cmake --build . --target install
FROM debian:12
RUN apt-get update && apt-get install -y libssl3 zlib1g && rm -rf /var/lib/apt/lists/*
COPY --from=build /usr/local/bin/telegram-bot-api /usr/local/bin/
WORKDIR /data
ENTRYPOINT ["telegram-bot-api", "--local", "--dir=/data"]services:
bot-api:
build: .
restart: unless-stopped
env_file: .env
volumes:
- ./data:/data
ports:
- "127.0.0.1:8081:8081"В .env лежат TELEGRAM_API_ID и TELEGRAM_API_HASH. Собирать образ при каждом обновлении не обязательно: соберите его один раз и храните в реестре контейнеров. Если бот тоже в контейнере, подключите к нему том ./data: в режиме --local он читает скачанные файлы прямо с диска.
Инструмент · 1 мин
Как переключить бота на локальный Bot API#
Запросы идут в том же формате, меняется только адрес: вместо https://api.telegram.org/bot<токен>/getMe бот обращается к http://127.0.0.1:8081/bot<токен>/getMe. В aiogram и python-telegram-bot для этого есть настройка своего сервера API.
Перед переключением вызовите logOut на облачном API: иначе Telegram не гарантирует, что все сообщения дойдут. После выхода вернуться в облако можно только через 10 минут. Для переезда между двумя своими серверами есть метод close: удалите вебхук, закройте экземпляр и перенесите подпапку бота из рабочей папки старого сервера.
Переезд бота на свой Bot API
Отмечайте шаги по порядку
05 · 1 мин
Вебхук через локальный Telegram Bot API#
Облачный API шлёт вебхук только по HTTPS и только на порты 443, 80, 88 и 8443. Локальный сервер отправляет его по обычному HTTP на любой порт и локальный адрес, например http://127.0.0.1:8080/ или имя контейнера бота в сети Compose. Домен и сертификат для вебхука больше не нужны.
06 · 1 мин
Вопросы о своём Telegram Bot API server#
Есть ли официальный 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.
Почему этому можно верить
Как мы проверяли
Источники цифр на этой странице: VPS и VDS серверы Таймвеб Клауд, timeweb.cloud/services/vds-vps, проверено 14 октября 2026; Реестр контейнеров Таймвеб Клауд, timeweb.cloud/services/container-registry, проверено 14 октября 2026; Маркетплейс приложений Таймвеб Клауд, timeweb.cloud/marketplace, проверено 14 октября 2026; Telegram Bot API: получение обновлений, setWebhook, лимиты файлов, logOut, core.telegram.org/bots/api, проверено 14 октября 2026; tdlib/telegram-bot-api: README, сборка, флаги и переезд бота, github.com/tdlib/telegram-bot-api, проверено 14 октября 2026.
Запустите свой сервер за пару минут
Почасовая оплата: тестовый стенд на сутки стоит десятки рублей, а не месячный тариф.
- NVMe-диски и гарантированная доля процессора
- Root-доступ и любой софт, от Docker до игровых серверов
- Маркетплейс: 91 приложение в один клик
- Бесплатный перенос проекта силами специалистов