Local Telegram Bot API: advantages, limitations of the standard API and setup via Docker

Local Telegram Bot API allows developers to run their own API server, providing significant advantages for handling large files, performance, and configuration flexibility. However, to understand the need for a local server, it’s important to consider the limitations of the standard Telegram Bot API that works via an HTTPS interface. In this article we’ll review the benefits of the Local Bot API, the limitations of the standard approach, and steps to set up a local server via Docker, including registering a bot to use with it.

🚀 Main advantages of the Local Bot API

1. Increased file handling limits

For developers whose bots actively work with media, a local API server opens new possibilities:

• Upload files up to 2 GB:
  Unlike the standard Bot API, which limits uploaded file size to 50 MB, the local server allows working with files up to 2000 MB (2 GB). This is ideal for bots that process videos, audio, or other large media files.

• Download files without restrictions:
  The local API allows downloading files from Telegram servers without size restrictions (up to 2000 MB), whereas the standard API limits downloads to 20 MB.

• Use of local path for uploads:
  The local API server supports specifying a local path or the file:// URI scheme for uploads, which eliminates the need to transmit files via HTTP requests.

2. Reduced network latency

A local API server can significantly improve performance:

• Latency reduction:
  Requests from your bot are first sent to your local API server and then forwarded to Telegram servers.
  If your bot and API server are in the same network or geographically close, this reduces network latency, enabling faster request handling.

3. Flexibility and increased limits for Webhook

Using a local API server expands webhook configuration options:

• HTTP support:
  Unlike the standard Bot API, which requires HTTPS, the local server allows using HTTP for webhooks, simplifying setup in some scenarios.

• Any IP and port:
  You can configure webhooks on any local IP address and any port, providing flexibility in server configuration.

• Increased number of connections:
  The local API server supports up to 100,000 concurrent webhook connections, which far exceeds the limits of the standard API (restricted by HTTPS and ports 443, 80, 88, 8443).

4. Faster file access

The getFile method returns an absolute local path (file_path), which allows avoiding additional download requests if files are already available on your server.

🛑 Limitations of the standard Telegram Bot API

🛠 Setting up Local Bot API via Docker

1. Preparation

Before starting, make sure you have Docker and Docker Compose installed, and you have an API ID and API Hash obtained at my.telegram.org.

Create a file .env:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

2. Docker Compose configuration

File docker-compose.yml:

version: "3.8"
services:
  telegram-bot-api:
    build: ./telegram-bot-api-builder
    container_name: telegram-local-api
    restart: unless-stopped
    environment:
      TELEGRAM_API_ID: ${TELEGRAM_API_ID}
      TELEGRAM_API_HASH: ${TELEGRAM_API_HASH}
    ports:
      - "8081:8081"
    volumes:
      - tgdata:/var/lib/telegram-bot-api
    command:
      - --api-id=${TELEGRAM_API_ID}
      - --api-hash=${TELEGRAM_API_HASH}
      - --http-port=8081
      - --dir=/var/lib/telegram-bot-api

volumes:
  tgdata:

3. Dockerfile

File telegram-bot-api-builder/Dockerfile:

# ---------- Stage 1: Build ----------
FROM ubuntu:24.04 AS builder

ARG DEBIAN_FRONTEND=noninteractive
# Позволяет зафиксировать конкретный коммит/тег при сборке:
# пример: --build-arg TELEGRAM_BOT_API_REF=v7.2
ARG TELEGRAM_BOT_API_REF=master

RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      build-essential g++ cmake git \
      libssl-dev zlib1g-dev ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Клонируем и фиксируемся на нужной ревизии
WORKDIR /src
RUN git clone https://github.com/tdlib/telegram-bot-api.git . --depth 1 --branch ${TELEGRAM_BOT_API_REF}

# Сборка
RUN mkdir -p build && cd build && \
    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local .. && \
    cmake --build . --target telegram-bot-api -j"$(nproc)"

# Сжимаем бинарник (уменьшаем размер)
RUN strip /src/build/telegram-bot-api || true


# ---------- Stage 2: Runtime ----------
FROM ubuntu:24.04

ARG DEBIAN_FRONTEND=noninteractive

# Минимальные зависимости рантайма:
# libssl3 для Ubuntu 24.04, zlib, сертификаты для исходящих запросов
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      libssl3 zlib1g ca-certificates curl && \
    rm -rf /var/lib/apt/lists/*

# Каталог данных + системный пользователь
RUN groupadd -r telegram-bot-api && \
    useradd  -r -g telegram-bot-api -d /var/lib/telegram-bot-api -s /sbin/nologin telegram-bot-api && \
    mkdir -p /var/lib/telegram-bot-api && \
    chown -R telegram-bot-api:telegram-bot-api /var/lib/telegram-bot-api

# Копируем бинарник
COPY --from=builder /src/build/telegram-bot-api /usr/local/bin/telegram-bot-api

# Порт по умолчанию (меняйте в docker-compose командой --http-port)
EXPOSE 8081

# Healthcheck: простой HTTP-пинг локального порта
ENV HEALTH_PORT=8081
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD curl -fsS "http://127.0.0.1:${HEALTH_PORT}/" >/dev/null || exit 1

USER telegram-bot-api
WORKDIR /var/lib/telegram-bot-api

# Параметры (api-id, api-hash, порты, директории) передаются через docker-compose:
#   command: ["--api-id=...", "--api-hash=...", "--http-port=8081", "--dir=/var/lib/telegram-bot-api"]
ENTRYPOINT ["/usr/local/bin/telegram-bot-api"]

Features of this version:

• Base is Ubuntu 24.04 with libssl3.
• Parallel build and strip of the binary to reduce size.
• HEALTHCHECK for container monitoring.
• Secure non-privileged user.
• Ability to set build tag TELEGRAM_BOT_API_REF for reproducibility.

4. Starting the server

docker-compose up -d

After start, the server will be available at:

http://localhost:8081

5. Check and register the bot

curl http://localhost:8081/bot<YOUR_TOKEN>/getMe

If you see a JSON response with the bot’s name — everything works.

6. Usage in code

Python (python-telegram-bot)

from telegram.ext import Updater
updater = Updater(token='YOUR_TOKEN', base_url='http://localhost:8081')

Node.js (node-telegram-bot-api)

const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot('YOUR_TOKEN', { baseUrl: 'http://localhost:8081' });

7. Webhook setup

curl -X POST \
  http://localhost:8081/bot<YOUR_TOKEN>/setWebhook \
  -d '{"url": "http://your_server_ip:8081/bot<YOUR_TOKEN>"}'

💡 Summary

Local Telegram Bot API is a powerful solution for:

• working with large files (up to 2 GB);
• reducing latency;
• flexible webhook configuration;
• high-load systems.

The standard API is suitable for:

• small projects;
• working with files up to 50 MB;
• typical HTTPS webhooks.

Setting up via Docker ensures reproducibility, easy updates, and isolation security. The Dockerfile is an optimal option for stable and easy building of the Telegram Bot API in production.

🔗 Useful links

• Official Telegram Bot API repository
• Telegram API Tools (my.telegram.org)
• Telegram Bot API documentation