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 superiores para Webhook

Usar un servidor API local amplía las opciones 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 cual 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 proporciona flexibilidad en la configuración del servidor.

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

4. Acceso acelerado a archivos

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

Todas las ventajas de esta sección funcionan solo si el servidor se ejecuta con la bandera --local. Sin ella, 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 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 el 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 esta bandera el servidor funciona con las mismas limitaciones que el servicio en la nube.
• TELEGRAM_API_ID y TELEGRAM_API_HASH el servidor los lee de las variables de entorno por sí mismo, por lo que no es necesario pasarlos también como argumentos --api-id y --api-hash.
• El puerto está publicado solo en 127.0.0.1. El servidor acepta solicitudes por un único token de bot sin otras verificaciones, por lo que no conviene exponerlo a Internet. Si el bot funciona 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 muestra 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 indica el hash del commit:
# --build-arg TELEGRAM_BOT_API_REF=<commit>
ARG TELEGRAM_BOT_API_REF=master

# Dependencias de compilación según la instrucción 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 está incluido 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 el tamaño)
RUN strip /src/build/telegram-bot-api || true


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

ARG DEBIAN_FRONTEND=noninteractive

# Dependencias mínimas en tiempo de ejecución:
# 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 (cámbialo en docker-compose con el argumento --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 — a través de variables de entorno
ENTRYPOINT ["/usr/local/bin/telegram-bot-api"]

Características de esta versión:

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

4. Arranque del servidor

docker compose up -d --build

Tras el arranque el servidor estará accesible en:

http://localhost:8081

5. Verificación y registro del bot

Si el bot ya funcionaba mediante el API en la nube, antes de cambiar al servidor local debe desconectarse de la nube con el método logOut. Si no, parte de las actualizaciones puede seguir yendo a los servidores de Telegram:

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

Tras una llamada exitosa, volver a la nube solo es posible pasados 10 minutos. Para mover un bot de un servidor local a otro, ejecuta en el servidor antiguo deleteWebhook y close.

Luego verifica 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 superior)

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 con el sufijo /bot: por defecto la biblioteca apunta a https://api.telegram.org/bot. La clase Updater(token, base_url=...) de ejemplos antiguos corresponde a la versión 13 y no funciona así en las versiones actuales. local_mode(True) es necesario cuando el servidor se ejecuta con --local: entonces get_file() devuelve la ruta local y la biblioteca no intenta descargar el archivo.

Cualquier otro lenguaje o biblioteca

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 biblioteca; búscalo en su documentación como base URL o API URL. Puedes probar sin biblioteca:

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

7. Configuración del 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 dirección del servidor Bot API. En el ejemplo el bot está ejecutado 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 solo solicitudes HTTP. Si es necesario acceder a él externamente por HTTPS, se coloca un proxy TLS delante — nginx, Caddy o HAProxy.

El servidor solo entiende HTTP/1.0 y HTTP/1.1. A las solicitudes con otra versión del protocolo responde 505 HTTP Version Not Supported, y las bibliotecas cliente convierten eso 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 esto es el parámetro http_version="2" en la solicitud; por defecto se usa "1.1", y basta con no cambiarlo. En otras bibliotecas 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 Bot API debe usarse HTTP/1.1. En nginx se configura con proxy_http_version 1.1; en el bloque location; HTTP/2 puede mantenerse en el lado de los clientes.

💡 Resumen

Local Telegram Bot API es adecuado 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.

Compilar en Docker proporciona una imagen reproducible y actualizaciones sencillas. Lo principal al migrar es: iniciar el servidor con --local, llamar a logOut para el API en la nube y no publicar el puerto del servidor en Internet.

🔗 Enlaces útiles

• Repositorio oficial Telegram Bot API
• Telegram API Tools (my.telegram.org)
• Documentación Telegram Bot API
• Instrucción oficial de compilación
• Local Bot API Server en python-telegram-bot