Telegram Bot API

Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless

· 9 min de lectura

Para desplegar un bot de Telegram, ejecuta su código en una máquina siempre encendida que pueda llegar a api.telegram.org y elige cómo recibirá las actualizaciones: long polling con getUpdates, que funciona en cualquier servidor sin dominio, o webhook, que necesita una URL HTTPS pública. Para bots con polling lo habitual es un VPS pequeño con systemd o un contenedor Docker; las plataformas serverless como Cloudflare Workers encajan con bots por webhook. Esta guía muestra cada opción con configuraciones listas para copiar, además de logs, reinicios y una checklist de lanzamiento.

Polling o webhook en el servidor

Telegram ofrece dos formas excluyentes de recibir actualizaciones y, en ambos casos, guarda las no entregadas durante 24 horas como máximo. La elección define lo que necesita el hosting de tu bot de Telegram:

Long polling (getUpdates)Webhook (setWebhook)
RedSolo HTTPS saliente; funciona detrás de NATURL HTTPS pública, puertos 443, 80, 88 u 8443, IPv4
ProcesoBucle de larga duraciónHandler HTTP; puede ser serverless
InstanciasExactamente una por tokenVarias detrás de una URL, sin problema
Hosts adecuadosVPS, Docker, servidor en casaVPS con proxy inverso, Cloudflare Workers, AWS Lambda, Vercel

Si el polling ya funciona en tu máquina, quédate con él: la propia guía de webhooks de Telegram dice que no hay nada de malo en usar getUpdates. Cambia a webhook cuando tu plataforma lo exija o cuando quieras repartir la carga entre varias instancias.

Un bot con polling listo para desplegar

El código listo para producción cumple tres cosas: lee el token de una variable de entorno, escribe logs en stdout y sobrevive a los errores de red en lugar de caerse. Este bot de eco hace las tres y llama a deleteWebhook al arrancar, porque getUpdates no funciona mientras haya un webhook configurado:

import logging
import os
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")

TOKEN = os.environ["BOT_TOKEN"]  # nunca escribas el token en el código
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def main():
    call("deleteWebhook")  # polling y webhook son excluyentes
    log.info("iniciado como @%s", call("getMe")["username"])
    offset = 0
    while True:
        try:
            updates = call("getUpdates", offset=offset, timeout=30)
        except Exception:
            log.exception("falló getUpdates, reintento en 5 s")
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            msg = update.get("message")
            if msg and "text" in msg:
                try:
                    call("sendMessage", chat_id=msg["chat"]["id"], text="Eco: " + msg["text"])
                except Exception:
                    log.exception("falló la actualización %s", update["update_id"])


if __name__ == "__main__":
    main()
const TOKEN = process.env.BOT_TOKEN; // nunca escribas el token en el código
if (!TOKEN) throw new Error("BOT_TOKEN no está definido");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

await call("deleteWebhook"); // polling y webhook son excluyentes
log("iniciado como @" + (await call("getMe")).username);

let offset = 0;
while (true) {
  let updates;
  try {
    updates = await call("getUpdates", { offset, timeout: 30 });
  } catch (err) {
    log("falló getUpdates, reintento en 5 s:", err.message);
    await sleep(5000);
    continue;
  }
  for (const update of updates) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (!msg?.text) continue;
    try {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Eco: " + msg.text });
    } catch (err) {
      log(`falló la actualización ${update.update_id}:`, err.message);
    }
  }
}

Guárdalos como bot.py (con requests en requirements.txt) o bot.mjs (Node.js 18+, sin dependencias). Los frameworks de la lista de librerías manejan el bucle por ti, pero los pasos de despliegue de abajo son los mismos.

Bot de Telegram en un VPS con systemd

Un VPS te da una máquina Linux normal. Deja que systemd arranque el bot al iniciar el sistema y lo reinicie si se cae:

  1. Crea un usuario sin permisos de login y copia el código a /opt/mybot; en Python, crea ahí un entorno virtual e instala las dependencias.
  2. Pon el token en /etc/mybot.env como una línea BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours y restringe el acceso con chmod 600.
  3. Crea el archivo de unidad /etc/systemd/system/mybot.service:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Actívalo y sigue los logs:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f        # logs en vivo
sudo systemctl restart mybot  # después de actualizar el código

Para un webhook en el mismo VPS, ejecuta el bot como servidor HTTP en un puerto local y pon delante nginx o Caddy para terminar TLS en el puerto 443; la guía de webhooks incluye un handler que valida el secret token.

Desplegar un bot de Telegram con Docker

Un contenedor empaqueta el runtime y las dependencias, así que el bot funciona igual en tu laptop y en cualquier host con Docker. Un Dockerfile para el bot en Python:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]

Constrúyelo y ejecútalo pasando el token en tiempo de ejecución, nunca dentro de la imagen:

docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot

--restart unless-stopped levanta el bot de nuevo tras caídas y reinicios del host. Deja .env fuera de Git y de la imagen (agrégalo a .dockerignore). Al volver a desplegar un bot con polling, detén el contenedor viejo antes de iniciar el nuevo: dos contenedores haciendo polling con el mismo token hacen que getUpdates falle con 409 Conflict.

Serverless: bot de Telegram en Cloudflare Workers

Las plataformas serverless ejecutan código solo cuando llega una petición, así que necesitan modo webhook. En Cloudflare Workers la dirección workers.dev por defecto ya sirve HTTPS en el puerto 443. Este Worker valida el encabezado del secret token, responde de inmediato y termina el trabajo en segundo plano con ctx.waitUntil:

// worker.js: despliega con "npx wrangler deploy"
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
      return new Response("Not found", { status: 404 });
    }
    const enc = new TextEncoder();
    const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
    const expected = enc.encode(env.WEBHOOK_SECRET);
    if (received.byteLength !== expected.byteLength ||
        !crypto.subtle.timingSafeEqual(received, expected)) {
      return new Response("Forbidden", { status: 403 });
    }
    const update = await request.json();
    ctx.waitUntil(handleUpdate(update, env)); // responde 200 ya y sigue trabajando
    return new Response("OK");
  },
};

async function handleUpdate(update, env) {
  const msg = update.message;
  if (!msg?.text) return;
  const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: msg.chat.id, text: "Eco: " + msg.text }),
  });
  if (!res.ok) console.error("falló sendMessage", res.status, await res.text());
}

Guarda ambos valores como secrets del Worker, despliega y registra la URL del Worker con el mismo secreto:

npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "replace-with-your-random-secret"}'

O completa setWebhook en Bot API Tester. El mismo patrón sirve en AWS Lambda (detrás de una function URL HTTPS o un API gateway) y en las funciones de Vercel: parsea el cuerpo JSON, valida el encabezado y devuelve 2XX rápido. Las plataformas limitan cuánto tiempo pueden correr una función y su trabajo en segundo plano, así que manda las tareas lentas a una cola. Telegram reintenta toda respuesta que no sea 2XX, de modo que una función que excede el tiempo o se cae recibe la misma actualización otra vez.

Hosting gratis o barato para un bot de Telegram

Requisitos del webhook en cualquier host

Después de cada deploy, abre getWebhookInfo en Bot API Tester: si pending_update_count crece o aparece un last_error_message reciente, Telegram no logra entregar las actualizaciones.

Variables de entorno, logs y reinicios

Checklist de despliegue

  1. El token viene de una variable de entorno o un secret; getMe responde bien en el servidor.
  2. Exactamente una instancia de polling por token, o un webhook con secret_token; nunca ambos.
  3. El proceso se reinicia solo tras caídas y reinicios.
  4. Los logs se recopilan y no contienen tokens.
  5. Los errores de una actualización se registran pero no tumban el bot; los handlers de webhook devuelven 2XX rápido.
  6. Con webhook, getWebhookInfo muestra la URL correcta y ningún error reciente.
  7. Para experimentar se usa un bot de pruebas aparte o el servidor de pruebas de Telegram, no el token de producción.

Solución de problemas de despliegue

SíntomaCausa y solución
409 Conflict: terminated by other getUpdates requestDos instancias hacen polling con un mismo token (el contenedor viejo, tu laptop). Detén todas menos una.
409 Conflict que menciona un webhook activoSigue configurado un webhook. Llama a deleteWebhook antes de hacer polling.
401 UnauthorizedLa variable del token está vacía, mal escrita o el token fue revocado. Verifícalo con getMe.
Funciona en local, pero en el servidor no hace nadaEl HTTPS saliente hacia api.telegram.org está bloqueado o no se carga el archivo de entorno. Revisa los logs.
El bot con webhook no recibe nadaMira last_error_message en getWebhookInfo: TLS, puerto incorrecto, 403 por secreto que no coincide o un handler que se cae.

¿Recién empiezas con bots? Comienza por cómo crear un bot en Telegram y vuelve aquí para desplegarlo.

Preguntas frecuentes

¿Dónde puedo alojar un bot de Telegram?

En cualquier lugar que pueda hacer peticiones HTTPS salientes: un VPS, un host con Docker, un servidor en casa o una plataforma serverless. Un bot con getUpdates no necesita dirección pública; un bot con webhook necesita una URL HTTPS pública en el puerto 443, 80, 88 u 8443.

¿Un bot en producción debe usar polling o webhook?

Ambos funcionan en producción. El long polling con getUpdates es lo más sencillo en un VPS o en Docker porque no requiere dominio ni certificado. El webhook es obligatorio en plataformas serverless, que solo ejecutan código cuando llega una petición.

¿Por qué recibo 409 Conflict después de desplegar mi bot?

O sigue configurado un webhook mientras el bot hace polling con getUpdates (llama a deleteWebhook), o dos copias del bot hacen polling a la vez, por ejemplo el contenedor viejo y el nuevo durante un deploy, o tu laptop y el servidor. Ejecuta exactamente una instancia de polling por token.

¿Cómo mantengo un bot de Telegram activo 24/7?

Ejecútalo bajo un supervisor de procesos que lo reinicie tras caídas y reinicios: un servicio systemd con Restart=always en un VPS o un contenedor Docker con --restart unless-stopped. Escribe los logs en stdout y revísalos con journalctl o docker logs.

¿Puedo correr un bot de Telegram en Cloudflare Workers?

Sí, en modo webhook. El Worker recibe cada actualización como una petición POST, valida el encabezado X-Telegram-Bot-Api-Secret-Token y llama a la Bot API con fetch. Registra su dirección HTTPS de workers.dev con setWebhook. Un bucle de long polling no encaja en este modelo.

¿Dónde guardo el token del bot en un servidor?

En una variable de entorno cargada desde un archivo que solo pueda leer el usuario del bot, o en el almacén de secretos de la plataforma (por ejemplo, un secret de Worker). Nunca subas el token a Git ni lo metas en una imagen de Docker. Si se filtra, revócalo en @BotFather.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más

Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.

Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo

Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.

Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes

Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.

Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start

Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.

Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard

Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.

Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes

Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Bot inline de Telegram: cómo activar el modo inline y responder consultas

Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.

Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones

Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.

Cómo probar una Mini App de Telegram: del navegador a Telegram real

Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.