Перейти к содержимому
RWP Shop Docs

Сервер и эксплуатация

Локальный Telegram Bot API

Запуск собственного сервера telegram-bot-api и подключение бота через TELEGRAM_API_URL

По умолчанию бот обращается к публичному серверу Telegram https://api.telegram.org. Вы можете развернуть собственный сервер telegram-bot-api и направить бота на него через переменную окружения TELEGRAM_API_URL.

  • Большие файлы — публичный API ограничивает загрузку до 20 МБ, скачивание до 20 МБ. Локальный сервер поднимает лимиты до 2 ГБ.
  • Локальные файлы — локальный сервер отдаёт скачанные файлы прямым путём на диске, без повторной загрузки по сети.
  • Скорость и независимость — нет общего rate-лимита публичного API, меньше задержек, работа при недоступности api.telegram.org напрямую.
  • Webhook и polling на своей инфраструктуре.

Локальный сервер требует ключей приложения Telegram (не путать с токеном бота):

  1. Войдите на my.telegram.org под своим аккаунтом.
  2. Откройте API development tools.
  3. Создайте приложение — получите api_id (число) и api_hash (строка).

Добавьте сервис в docker-compose.yml рядом с ботом:

services:
telegram-bot-api:
image: aiogram/telegram-bot-api:latest
environment:
TELEGRAM_API_ID: "1234567"
TELEGRAM_API_HASH: "abcdef0123456789abcdef0123456789"
TELEGRAM_LOCAL: 1 # режим локальных файлов (прямые пути на диске)
volumes:
- telegram-bot-api-data:/var/lib/telegram-bot-api
ports:
- "8081:8081"
restart: unless-stopped
volumes:
telegram-bot-api-data:
telegram-bot-api \
--api-id=1234567 \
--api-hash=abcdef0123456789abcdef0123456789 \
--local \
--http-port=8081

Перед первым подключением к локальному серверу вызовите метод logOut на облачном API (именно на api.telegram.org, не на локальном сервере):

curl -X POST https://api.telegram.org/bot<TELEGRAM_TOKEN>/logOut
# {"ok":true,"result":true}
  • Замените <TELEGRAM_TOKEN> на ваш токен из TELEGRAM_TOKEN.
  • После logOut подождите ~10 минут. Если в ответ пришёл 429 Too Many Requests — выждите указанное в retry_after время и повторите.
  • Только после успешного logOut запускайте бота с TELEGRAM_API_URL.

Укажите адрес локального сервера в переменной окружения бота:

TELEGRAM_API_URL=http://telegram-bot-api:8081
  • Внутри Docker-сети — имя сервиса: http://telegram-bot-api:8081.
  • На том же хосте — http://127.0.0.1:8081.
  • Без слеша в конце не обязательно — он обрезается автоматически.

Если переменная пуста или не задана, бот использует https://api.telegram.org (поведение по умолчанию).

При старте в логах появится строка подтверждения:

Telegram bot using custom API server url=http://telegram-bot-api:8081
  1. Перезапустите контейнер бота после установки TELEGRAM_API_URL.
  2. Убедитесь, что в логах есть строка Telegram bot using custom API server.
  3. Проверьте доступность сервера:
curl http://127.0.0.1:8081/
# Ответ "Unauthorized" — нормально: сервер жив, токен в запросе не передан

Чтобы вернуться на публичный API, бота нужно так же отвязать — но теперь от локального сервера:

  1. Остановите бота.

  2. Вызовите logOut на локальном сервере:

    curl -X POST http://127.0.0.1:8081/bot<TELEGRAM_TOKEN>/logOut
  3. Удалите TELEGRAM_API_URL (или оставьте пустым) и перезапустите бота — он снова подключится к api.telegram.org.

Симптом Причина / решение
getMe ... unexpected end of JSON input при старте Бот не отвязан от облака. Вызовите logOut на api.telegram.org (см. раздел выше).
Бот не стартует, ошибки сети Неверный TELEGRAM_API_URL или сервер недоступен из сети контейнера. Проверьте имя сервиса и порт.
logOut вернул 429 Telegram ограничивает частоту. Подождите время из retry_after и повторите.
Файлы не читаются При TELEGRAM_LOCAL=1 том с файлами не примонтирован в контейнер бота по тому же пути.
Хочу обойти только блокировку Используйте TELEGRAM_PROXY_URL вместо локального сервера.