Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless
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) | |
|---|---|---|
| Red | Solo HTTPS saliente; funciona detrás de NAT | URL HTTPS pública, puertos 443, 80, 88 u 8443, IPv4 |
| Proceso | Bucle de larga duración | Handler HTTP; puede ser serverless |
| Instancias | Exactamente una por token | Varias detrás de una URL, sin problema |
| Hosts adecuados | VPS, Docker, servidor en casa | VPS 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:
- 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. - Pon el token en
/etc/mybot.envcomo una líneaBOT_TOKEN=123456789:AAEexampleTokenReplaceWithYoursy restringe el acceso conchmod 600. - 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
- Los planes gratuitos serverless sirven para bots por webhook con tráfico moderado y handlers cortos.
- Un VPS pequeño es la opción más flexible: polling o webhook, cualquier lenguaje y una base de datos junto al bot.
- Un servidor en casa o una computadora de placa única funciona con polling, porque no hace falta ninguna conexión entrante; la disponibilidad depende de tu luz y tu internet.
- Las plataformas de contenedores que mantienen un proceso corriendo pueden alojar un bot con polling; revisa que no duerman las apps inactivas.
Requisitos del webhook en cualquier host
- Solo HTTPS, TLS 1.2 o superior, un certificado que coincida con tu dominio con la cadena completa, o un certificado autofirmado subido mediante
certificate. - Puertos 443, 80, 88 u 8443; IPv4 (los webhooks no admiten IPv6); sin redirecciones.
- Las peticiones llegan desde
149.154.160.0/20y91.108.4.0/22; Telegram advierte que los rangos pueden cambiar. - Define
secret_token(de 1 a 256 caracteresA-Z a-z 0-9 _ -) y valida el encabezadoX-Telegram-Bot-Api-Secret-Token.
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
- Token: solo en una variable de entorno o un almacén de secretos, nunca en Git, en imágenes ni en código cliente. Si se filtra, revócalo como se explica en la guía del token del bot y actualiza el servidor.
- Logs: escribe en stdout/stderr y deja que journald, Docker o la plataforma los recojan. No registres las URL completas de las peticiones, porque contienen el token.
- Reinicios: un supervisor (
Restart=always,--restart unless-stopped) se encarga de las caídas. Telegram guarda del lado suyo qué actualizaciones están confirmadas: una actualización queda confirmada cuando se llama agetUpdatescon unoffsetmayor, así que tras un reinicio el bot recibe solo las no confirmadas. El último lote antes de una caída puede llegar dos veces; elimina duplicados porupdate_iddonde importe. - Límites de frecuencia: ante
429 Too Many Requests, esperaretry_aftersegundos; consulta los límites de la Telegram Bot API.
Checklist de despliegue
- El token viene de una variable de entorno o un secret;
getMeresponde bien en el servidor. - Exactamente una instancia de polling por token, o un webhook con
secret_token; nunca ambos. - El proceso se reinicia solo tras caídas y reinicios.
- Los logs se recopilan y no contienen tokens.
- Los errores de una actualización se registran pero no tumban el bot; los handlers de webhook devuelven 2XX rápido.
- Con webhook,
getWebhookInfomuestra la URL correcta y ningún error reciente. - 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íntoma | Causa y solución |
|---|---|
409 Conflict: terminated by other getUpdates request | Dos instancias hacen polling con un mismo token (el contenedor viejo, tu laptop). Detén todas menos una. |
409 Conflict que menciona un webhook activo | Sigue configurado un webhook. Llama a deleteWebhook antes de hacer polling. |
401 Unauthorized | La 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 nada | El 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 nada | Mira 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.
Guías relacionadas
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.