API local de Telegram para bots: ventajas, limitaciones de la API estándar y configuración con Docker

Local Telegram Bot API permite a los desarrolladores ejecutar su propio servidor API, ofreciendo ventajas significativas en el trabajo 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 de Local Bot API, las limitaciones del enfoque estándar y los pasos para configurar un servidor local mediante Docker, incluyendo el registro del bot para usarlo con él.

🚀 Principales ventajas de Local Bot API

1. Límites aumentados para trabajar con archivos

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

• Subida de archivos de 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 vídeos, audio u otros medios grandes.

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

• Uso de rutas locales para la subida:
  El servidor API local soporta especificar una ruta local o el esquema URI file:// para subir archivos, lo que evita la necesidad de transmitir archivos mediante solicitudes HTTP.

2. Reducción de la latencia (Latency)

El servidor API local puede mejorar considerablemente el rendimiento:

• Reducción de la 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 cerca, esto permite reducir la latencia de red, proporcionando un procesamiento más rápido de las solicitudes.

3. Flexibilidad y límites aumentados 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 usar 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 cualquier puerto, lo que brinda flexibilidad en la configuración del servidor.

• Mayor número de conexiones:
  El servidor API local soporta hasta 100 000 conexiones simultáneas para webhooks, superando significativamente los límites del API estándar (limitados por HTTPS y los puertos 443, 80, 88, 8443).

4. Acceso acelerado a archivos

El método getFile devuelve la ruta local absoluta (file_path), lo que permite evitar solicitudes adicionales para descargar archivos si ya están disponibles en tu servidor.

🛑 Limitaciones del Telegram Bot API estándar

🛠 Configuración de Local Bot API con Docker

1. Preparación para el arranque

Antes de comenzar, 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:

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

Archivo telegram-bot-api-builder/Dockerfile:

# ---------- Etapa 1: Compilación ----------
FROM ubuntu:24.04 AS builder

ARG DEBIAN_FRONTEND=noninteractive
# Permite fijar un commit/etiqueta específicos durante la compilación:
# ejemplo: --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/*

# Clonamos y fijamos la revisión deseada
WORKDIR /src
RUN git clone https://github.com/tdlib/telegram-bot-api.git . --depth 1 --branch ${TELEGRAM_BOT_API_REF}

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

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


# ---------- Etapa 2: Tiempo de ejecución ----------
FROM ubuntu:24.04

ARG DEBIAN_FRONTEND=noninteractive

# Dependencias mínimas en tiempo de ejecución:
# libssl3 para Ubuntu 24.04, zlib, certificados para solicitudes salientes
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      libssl3 zlib1g ca-certificates curl && \
    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 && \
    chown -R telegram-bot-api:telegram-bot-api /var/lib/telegram-bot-api

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

# Puerto por defecto (cámbialo en docker-compose con el comando --http-port)
EXPOSE 8081

# Healthcheck: ping HTTP simple al puerto local
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

# Parámetros (api-id, api-hash, puertos, directorios) se pasan a través de docker-compose:
#   command: ["--api-id=...", "--api-hash=...", "--http-port=8081", "--dir=/var/lib/telegram-bot-api"]
ENTRYPOINT ["/usr/local/bin/telegram-bot-api"]

Características de esta versión:

• Base actual — Ubuntu 24.04 con libssl3.
• Compilación en paralelo y strip del binario para reducir tamaño.
• HEALTHCHECK para monitorizar el contenedor.
• Usuario no privilegiado por seguridad.
• Posibilidad de fijar la etiqueta de compilación TELEGRAM_BOT_API_REF para reproducibilidad.

4. Arrancar el servidor

docker-compose up -d

Después del arranque el servidor estará disponible en:

http://localhost:8081

5. Verificación y registro del bot

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)

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. Configuración de Webhook

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

💡 Resumen

Local Telegram Bot API es una solución potente para:

• trabajar con archivos grandes (hasta 2 GB);
• reducir la latencia;
• 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 típicos.

La configuración mediante Docker garantiza reproducibilidad, actualizaciones sencillas y aislamiento seguro. El Dockerfile es una opción óptima para una compilación estable y ligera de Telegram Bot API en producción.

🔗 Enlaces útiles

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