Local Telegram Bot API: ventajas, limitaciones del API estándar y configuración a través de Docker

Local Telegram Bot API permite a los desarrolladores ejecutar su propio servidor API, proporcionando ventajas significativas al trabajar con archivos grandes, rendimiento y flexibilidad de configuración. Sin embargo, para entender la necesidad de un servidor local es importante considerar las limitaciones del Telegram Bot API estándar que funciona a través de la interfaz HTTPS. En este artículo revisaremos las ventajas del Local Bot API, las limitaciones del enfoque estándar y los pasos para configurar un servidor local mediante Docker, incluida la registración del bot para usarlo.

🚀 Principales ventajas del Local Bot API

1. Límites aumentados para trabajo con archivos

Para desarrolladores cuyos bots manejan activamente medios, el servidor API local abre nuevas posibilidades:

• Subida de archivos hasta 2 GB:
  A diferencia del Bot API estándar, que limita el tamaño de los archivos subidos a 50 MB, el servidor local permite trabajar con archivos de hasta 2000 MB (2 GB). Esto es ideal para bots que procesan videos, audio u otros archivos multimedia grandes.

• Descarga de archivos sin restricciones:
  El API local permite descargar archivos desde los servidores de Telegram sin restricciones de tamaño (hasta 2000 MB), mientras que el API estándar limita la descarga de archivos a 20 MB.

• Uso de rutas locales para la carga:
  El servidor API local admite especificar una ruta local o el esquema URI file:// para subir archivos, lo que elimina la necesidad de transferir archivos mediante solicitudes HTTP.

2. Reducción de la latencia de red (Latency)

El servidor API local puede mejorar significativamente el rendimiento:

• Reducción de latencia:
  Las solicitudes de tu bot se envían primero a tu servidor API local y luego se reenvían a los servidores de Telegram.
  Si tu bot y el servidor API están en la misma red o geográficamente cercanos, esto permite reducir la latencia de red y obtener un procesamiento de solicitudes más rápido.

3. Flexibilidad y límites ampliados para Webhook

Usar un servidor API local amplía las posibilidades de configuración de webhooks:

• Soporte HTTP:
  A diferencia del Bot API estándar, que requiere HTTPS, el servidor local permite utilizar HTTP para webhooks, lo que simplifica la configuración en algunos escenarios.

• Cualquier IP y puerto:
  Puedes configurar webhooks en cualquier dirección IP local y en cualquier puerto, lo que ofrece flexibilidad en la configuración del servidor.

• Más conexiones simultáneas:
  El parámetro max_webhook_connections en el servidor local puede aumentarse hasta 100 000 (por defecto en modo --local — 100). En el API estándar son válidos valores de 1 a 100, por defecto 40, y el webhook sólo se acepta por HTTPS en los puertos 443, 80, 88 o 8443.

4. Acceso acelerado a archivos

En modo --local el método getFile devuelve la ruta local absoluta del archivo (file_path) y no requiere una descarga separada. Para que el bot pueda leer dicho archivo, debe tener acceso al directorio de datos del servidor — por ejemplo, un volumen compartido de Docker.

Todas las ventajas de esta sección funcionan sólo cuando el servidor se ejecuta con el flag --local. Sin él, el servidor local se comporta como en la nube: los mismos límites de archivos y los mismos requisitos para webhooks.

🛑 Limitaciones del Telegram Bot API estándar

🛠 Configuración del Local Bot API mediante Docker

1. Preparación para el arranque

Antes de empezar, asegúrate de tener instalados Docker y Docker Compose, y de contar con API ID y API Hash obtenidos en my.telegram.org.

Crea el archivo .env:

TELEGRAM_API_ID=tu_api_id
TELEGRAM_API_HASH=tu_api_hash

2. Configuración de Docker Compose

Archivo docker-compose.yml:

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:
      - "127.0.0.1:8081:8081"
    volumes:
      - tgdata:/var/lib/telegram-bot-api
    command:
      - --local
      - --http-port=8081
      - --dir=/var/lib/telegram-bot-api
      - --temp-dir=/tmp/telegram-bot-api

volumes:
  tgdata:

Qué es importante en esta configuración:

• --local activa el modo local: archivos hasta 2000 MB, webhooks por HTTP en cualquier puerto, rutas locales en getFile. Sin este flag el servidor funciona con las mismas limitaciones que en la nube.
• TELEGRAM_API_ID y TELEGRAM_API_HASH el servidor las lee directamente de las variables de entorno, por lo que no es necesario pasarlas también como argumentos --api-id y --api-hash.
• El puerto está publicado sólo en 127.0.0.1. El servidor acepta solicitudes por un único token de bot sin otras comprobaciones, no debe exponerse a Internet. Si el bot se ejecuta en el mismo proyecto Compose, se comunica con el servidor por el nombre del servicio, http://telegram-bot-api:8081, y no es necesario publicar el puerto externamente.
• La línea version: al inicio del archivo está obsoleta: Docker Compose moderno la ignora y emite una advertencia.

3. Dockerfile

Archivo telegram-bot-api-builder/Dockerfile:

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

ARG DEBIAN_FRONTEND=noninteractive
# Rama o commit para la compilación; para reproducibilidad especifica el hash del commit:
# --build-arg TELEGRAM_BOT_API_REF=<commit>
ARG TELEGRAM_BOT_API_REF=master

# Dependencias de compilación según la guía oficial (gperf es obligatorio)
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      make git zlib1g-dev libssl-dev gperf cmake g++ ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# El repositorio se clona recursivamente: TDLib se incluye como submódulo
WORKDIR /src
RUN git clone --recursive https://github.com/tdlib/telegram-bot-api.git . && \
    git checkout "${TELEGRAM_BOT_API_REF}" && \
    git submodule update --init --recursive

# Compilación
RUN mkdir -p build && cd build && \
    cmake -DCMAKE_BUILD_TYPE=Release .. && \
    cmake --build . --target telegram-bot-api -j"$(nproc)"

# Comprimimos el binario (reducimos tamaño)
RUN strip /src/build/telegram-bot-api || true


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

ARG DEBIAN_FRONTEND=noninteractive

# Dependencias mínimas de runtime:
# en Ubuntu 24.04 la librería OpenSSL se llama libssl3t64
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      libssl3t64 zlib1g ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Directorio de datos + usuario del sistema
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 /tmp/telegram-bot-api && \
    chown -R telegram-bot-api:telegram-bot-api /var/lib/telegram-bot-api /tmp/telegram-bot-api

# Copiamos el binario
COPY --from=builder /src/build/telegram-bot-api /usr/local/bin/telegram-bot-api

# Puerto por defecto (modifica en docker-compose con la opción --http-port)
EXPOSE 8081

# Healthcheck: comprobamos que el servidor acepta conexiones TCP en el puerto
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD bash -c 'exec 3<>/dev/tcp/127.0.0.1/8081' || exit 1

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

# Los parámetros se pasan mediante docker-compose (command), las claves API mediante variables de entorno
ENTRYPOINT ["/usr/local/bin/telegram-bot-api"]

Características de esta versión:

• Dependencias y git clone --recursive — como en la guía oficial de compilación. Sin gperf y sin el submódulo TDLib la compilación fallará.
• Base — Ubuntu 24.04; en runtime se necesita el paquete libssl3t64.
• Compilación paralela y strip del binario para reducir tamaño.
• HEALTHCHECK verifica que el puerto acepta conexiones. La comprobación con curl -f a la raíz aquí no es apropiada: el servidor responde a esa solicitud con un error.
• El servidor se ejecuta bajo un usuario sin privilegios.
• El argumento TELEGRAM_BOT_API_REF permite fijar la compilación en un commit concreto.

4. Arranque del servidor

docker compose up -d --build

Tras el arranque el servidor estará disponible en:

http://localhost:8081

5. Comprobación y registro del bot

Si el bot ya funcionaba mediante el API en la nube, antes de pasar al servidor local debe desconectarse de la nube con el método logOut. De lo contrario, parte de las actualizaciones podría seguir yendo a los servidores de Telegram:

curl https://api.telegram.org/bot<YOUR_TOKEN>/logOut

Tras una llamada exitosa, recuperar el bot en la nube sólo será posible pasados 10 minutos. Para trasladar un bot de un servidor local a otro, llama en el servidor antiguo a deleteWebhook y close.

Luego comprueba el servidor local:

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

Si ves una respuesta JSON con el nombre del bot — todo funciona.

6. Uso en código

Python (python-telegram-bot 20 y posteriores)

from telegram.ext import ApplicationBuilder

application = (
    ApplicationBuilder()
    .token("YOUR_TOKEN")
    .base_url("http://localhost:8081/bot")
    .base_file_url("http://localhost:8081/file/bot")
    .local_mode(True)
    .build()
)

La dirección se indica junto con el sufijo /bot: por defecto la librería apunta a https://api.telegram.org/bot. La clase Updater(token, base_url=...) de ejemplos antiguos pertenece a la versión 13 y no funciona así en versiones actuales. local_mode(True) es necesario cuando el servidor se ejecuta con --local: entonces get_file() devuelve la ruta local y la librería no intenta descargar el archivo.

Cualquier otro lenguaje o librería

El Bot API es una interfaz HTTP normal: basta con reemplazar en el cliente la dirección https://api.telegram.org por la de tu servidor. El nombre del parámetro depende de la librería; busca en su documentación base URL o API URL. Puedes comprobar el funcionamiento sin librería:

curl -X POST "http://localhost:8081/bot<YOUR_TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Comprobación del servidor local"}'

7. Configuración de Webhook

curl -X POST "http://localhost:8081/bot<YOUR_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "http://bot:8443/telegram-webhook"}'

En url se indica la dirección de tu bot — la aplicación que recibe las actualizaciones, no la del servidor Bot API. En el ejemplo el bot se ejecuta en el mismo proyecto Compose como servicio bot y escucha el puerto 8443. En modo --local el webhook puede ser HTTP, en cualquier puerto y en una dirección local.

8. HTTPS y error de versión HTTP

El servidor Bot API acepta únicamente solicitudes HTTP. Si necesitas acceder a él desde fuera por HTTPS, se coloca un proxy TLS delante — nginx, Caddy o HAProxy.

El servidor sólo entiende HTTP/1.0 y HTTP/1.1. A solicitudes con otra versión del protocolo responde 505 HTTP Version Not Supported, y las librerías cliente convierten esto en mensajes como «self hosted bot api instances only support HTTP/1.1». Las causas suelen ser dos:

• El cliente está configurado para HTTP/2. En python-telegram-bot es el parámetro http_version="2" de la solicitud; por defecto se usa "1.1", y basta con no cambiarlo. En otras librerías desactiva HTTP/2 para la dirección del servidor local.
• El proxy se comunica con el servidor por HTTP/2. Entre el proxy y el servidor Bot API debe haber HTTP/1.1. En nginx se establece proxy_http_version 1.1; en el bloque location; HTTP/2 puede dejarse en el lado de los clientes.

💡 Resumen

Local Telegram Bot API es adecuado para:

• trabajar con archivos grandes (hasta 2 GB);
• reducir latencias;
• configuración flexible de webhooks;
• sistemas de alta carga.

El API estándar es adecuado para:

• proyectos pequeños;
• trabajo con archivos hasta 50 MB;
• webhooks HTTPS estándar.

Compilar en Docker proporciona una imagen reproducible y una actualización sencilla. Lo principal al migrar es ejecutar el servidor con --local, llamar a logOut para el API en la nube y no exponer el puerto del servidor a Internet.

🔗 Enlaces útiles

• Официальный репозиторий Telegram Bot API
• Telegram API Tools (my.telegram.org)
• Документация Telegram Bot API
• Официальная инструкция по сборке
• Local Bot API Server в python-telegram-bot