Cómo alojar un bot de Telegraf 24/7 (Telegram, Node.js)

Para alojar un bot de Telegraf 24/7 lo ejecutas en una máquina que siempre está encendida: un VPS Linux con un servicio systemd que lo vuelve a iniciar cuando se detiene, o un plan para bots en PlayNHost (desde US$1.99 al mes), donde el panel instala tus paquetes, le da el token a tu código y vuelve a iniciar el bot si se cae. En nuestra prueba, un bot con Telegraf 4.16.3 usó unos 60 MB de memoria con Node.js 22. bot.launch() de Telegraf usa long polling por defecto, que es justo lo que necesitan nuestros planes: todavía no tienen una dirección HTTPS pública para un webhook. Los pasos en PlayNHost:

1. En alojamiento para bots de Telegram, haz clic en Crear servidor en un plan. En la ventana del pedido, responde ¿Para qué plataforma es tu bot? con Telegram y elige Node.js.
2. Abre tu servidor en el panel. La tarjeta Configura tu bot en Resumen se abre en Conectar con Telegram; su primer paso, Qué se ejecuta, debería decir Este bot ejecuta Node.js Bot.
3. En Conectar con Telegram, pega el token de @BotFather en Pega el token de tu bot, haz clic en Conexión, comprueba el nombre del bot que aparece y haz clic en Sí, continuar.
4. En Tu código, haz clic en Subir archivos y sube tu package.json y tu index.js sin node_modules, o haz clic en Conectar Git.
5. En la página Bot, panel Código, comprueba que Archivo de entrada es el archivo que inicia tu bot (index.js por defecto). Haz clic en Guardar si lo cambias.
6. Haz clic en Iniciar bot y abre Console. npm instala Telegraf en el primer inicio, luego tu bot imprime Logged in as @your_bot y el indicador de Resumen pasa a En línea en Telegram.
7. En la página Bot, panel Telegram, haz clic en Abrir en Telegram y envía /start a tu bot.

Cómo crear el bot en @BotFather y los pasos del panel se explican en Cómo alojar un bot de Telegram. Esta página trata de Telegraf en sí: qué usa en un servidor y qué conviene saber antes de alojarlo.

Qué medimos

Cómo: en nuestro propio nodo, en un contenedor desechable configurado como un plan de bot de 1 GB (la imagen de Node.js 22 y el comando de inicio de nuestro tipo de bot Node.js, con el límite de memoria de Node al 80 por ciento), cada bot llamó a Telegram con un token falso, que Telegram rechazó. La memoria es la memoria residente 15 segundos después de esa respuesta, el tiempo de inicio va desde launch hasta la respuesta y cada cifra es la mediana de las ejecuciones 2 a 4.

Son mínimos: un bot sin chats y sin datos todavía. Tu propio código, lo que guarda en memoria y el número de chats se suman, así que la librería es una parte pequeña de los 0.5 GB del plan STARTER.

Un bot mínimo con Telegraf

Responde a /start, lee el token que le da el panel e imprime una línea de listo. Pon los dos archivos en la carpeta principal de tu bot.

package.json

{
  "name": "my-telegraf-bot",
  "private": true,
  "main": "index.js",
  "dependencies": {
    "telegraf": "^4.16.3"
  }
}

index.js

const { Telegraf } = require("telegraf");

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN);

bot.start((ctx) => ctx.reply("Hello! I am running on PlayNHost."));

// Without this, an error in one command stops the whole bot.
bot.catch((err, ctx) => {
  console.error(`Error while handling update ${ctx.update.update_id}:`, err);
});

// launch() only returns when the bot stops, so the ready line goes in its callback.
bot.launch(() => console.log(`Logged in as @${bot.botInfo.username}`)).catch((err) => {
  if (err.code === 401) {
    console.log("Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.");
  } else {
    console.error(err);
  }
  process.exit(1);
});

process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

Los ejemplos de Telegraf leen process.env.BOT_TOKEN. El panel le da el token a tu código como TELEGRAM_BOT_TOKEN y también como BOT_TOKEN, TOKEN, TELEGRAM_TOKEN y TELOXIDE_TOKEN, así que esos ejemplos funcionan sin cambios. La línea Logged in as @your_bot es la que hace que el indicador pase a En línea en Telegram.

Si el token es incorrecto

En nuestra prueba, con un token falso, el bot.launch() de Telegraf falló con un TelegramError cuyo err.code es 401. Impreso como nombre y mensaje, dice:

Error: 401: Unauthorized

El nombre aparece como Error porque la clase de error de Telegraf no define un nombre propio. Telegraf no reintenta un token rechazado: bot.launch() falla de inmediato, y lo mismo pasa con un bot que no recibió ningún token (401: Bot Token is required). El bot de arriba captura ambos casos e imprime en su lugar Telegram did not accept the bot token. Paste the current one from @BotFather, then restart., y el panel muestra el aviso Telegram no aceptó el token de tu bot encima de Console. Para solucionarlo, en @BotFather envía /mybots, elige tu bot, luego API Token y copia el token otra vez. En la página Bot, panel Telegram, haz clic en Reemplazar token, pégalo, haz clic en Guardar token y luego en Reiniciar ahora.

Qué saber de Telegraf en un servidor

• Versiones: la última de Telegraf es la 4.16.3, publicada el 29 feb 2024. La 4.16.0 (25 feb 2024) añadió la Bot API 7.0 y 7.1 de Telegram; el registro de cambios de Telegram va por la Bot API 10.3 (24 ago 2026). El último push al repositorio de GitHub fue el 24 sep 2026. En nuestra prueba, la 4.16.3 se instaló y arrancó con normalidad en Node.js 22.
• La línea de listo va en el callback de launch(). bot.launch() solo devuelve el control cuando el bot se detiene, así que un console.log después de await bot.launch() nunca se imprime mientras el bot funciona. Desde la 4.16.0, launch() acepta un callback que Telegraf llama cuando Telegram ha aceptado el token, con bot.botInfo ya rellenado.
• Un error en un comando detiene el bot si no defines bot.catch. El manejador por defecto de Telegraf imprime Unhandled error while processing con la actualización y vuelve a lanzar el error, lo que termina el polling, así que el proceso se detiene. Nuestro panel vuelve a iniciar un bot caído en aproximadamente un minuto, pero hasta entonces está desconectado. Con bot.catch, como arriba, el error se imprime y el bot sigue.
• Cada actualización tiene 90 segundos. Una actualización cuyos manejadores tardan más se notifica como error (la opción handlerTimeout, 90,000 ms por defecto), que pasa entonces a bot.catch. Pasa new Telegraf(token, { handlerTimeout: ... }) para tareas más largas.
• Un webhook que quedó en el bot se elimina por ti. bot.launch() sin la opción webhook llama a deleteWebhook antes de hacer polling y conserva los mensajes en espera salvo que pases dropPendingUpdates: true. bot.launch({ webhook: ... }) necesita una dirección HTTPS pública, que estos planes todavía no incluyen: usa bot.launch() a secas. Si vienes de un host con webhook: Cómo mover un bot de Telegram a PlayNHost.
• Otra copia del bot detiene a esta. Con 409 Conflict (el mismo token haciendo polling en otro sitio), el polling de Telegraf lanza un error en lugar de reintentar. El panel muestra Tu bot también se está ejecutando en otro sitio: detén la copia en tu PC o en tu host anterior. Mira Solucionar el error 409 Conflict de un bot de Telegram. Mientras hace polling, los errores de red, 429 y los errores 5xx de Telegram se reintentan tras la espera que pide Telegram, o 5 segundos.
• Versión de Node.js: Telegraf 4.16.3 pide Node.js 12.20 o 14.13.1 y posteriores. El Entorno de ejecución del panel Código ofrece Node.js 20, 22 (recommended), 24, 25 y 26.
• Límite de memoria: el script de inicio fija NODE_OPTIONS=--max-old-space-size al 80 por ciento de la memoria de tu plan, para que al resto del proceso le quede espacio. Detalles del script de inicio de Node.js: Cómo alojar un bot de Discord en Node.js.

Alójalo tú mismo en un VPS Linux

En Debian 12 o 13, o en Ubuntu 24.04, basta con el paquete de la distribución para Telegraf (Debian 12 trae Node.js 18.20, Debian 13 trae 20.19, Ubuntu 24.04 trae 18.19):

sudo apt update
sudo apt install nodejs npm
node --version

Crea un usuario para el bot, copia tus archivos e instala los paquetes:

sudo useradd --system --create-home --home-dir /opt/mybot mybot
sudo cp package.json index.js /opt/mybot/
sudo chown -R mybot: /opt/mybot
cd /opt/mybot && sudo -u mybot npm install --omit=dev

Mantén el token fuera de tu código, en un archivo que solo root pueda leer:

sudo sh -c 'echo "TELEGRAM_BOT_TOKEN=123456789:your-token" > /etc/mybot.env'
sudo chmod 600 /etc/mybot.env

Crea /etc/systemd/system/mybot.service:

[Unit]
Description=Telegraf Telegram bot
Wants=network-online.target
After=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/usr/bin/node index.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Inícialo ahora y en cada arranque, y luego sigue su salida:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
sudo journalctl -u mybot -f

Restart=always vuelve a iniciar el bot tras una caída o un process.exit(1). systemctl stop mybot envía SIGTERM, que las líneas process.once convierten en bot.stop(). Detén antes cualquier otra copia, o Telegram responderá a ambas con 409 Conflict.

Alojarlo tú mismo o un plan para bots

En un VPS que gestionas tú, te encargas de:

• Las actualizaciones y la seguridad del sistema operativo, y las actualizaciones de Node.js.
• Ejecutar npm install tras cada cambio, el archivo de servicio, el archivo del token y sus permisos.
• Leer journalctl para averiguar por qué se detuvo el bot.
• Las copias de seguridad de los datos del bot.

A cambio, un VPS ejecuta lo que sea, y puedes darle un dominio con HTTPS para un webhook.

En un plan para bots de PlayNHost, el panel hace esto por ti:

• Un selector de versión de Node.js, y npm install cuando cambian package.json, el archivo de bloqueo o la versión de Node.js.
• El token se comprueba con Telegram antes de guardarlo, se almacena cifrado y se entrega a tu código.
• Reinicio del bot tras una caída. Si vuelve a caerse en menos de un minuto, queda detenido y Console dice por qué.
• Avisos encima de Console que nombran la causa cuando Telegram rechaza el token, hay otra copia en ejecución o hay un webhook activo, con un botón Quitar webhook en el panel Telegram.
• Subida de archivos, despliegues con Git y copias de seguridad desde el panel.

Preguntas frecuentes

¿Por qué no se imprime nada después de await bot.launch()?

Porque bot.launch() espera a que termine el polling, y el polling dura tanto como el bot. El código posterior solo se ejecuta cuando el bot se detiene. Pon los mensajes de arranque en el callback, bot.launch(() => ...), y registra los comandos antes de llamar a launch().

¿Puedo seguir usando Telegraf o debería pasarme a grammY?

Un bot de Telegraf 4 que funciona se ejecuta en nuestros planes tal cual: no hay nada que cambiar para alojarlo. Su última versión es de febrero de 2024, así que los métodos que Telegram añadió después de la Bot API 7.1 no tienen atajo en Telegraf. grammY 1.46.0 (26 ago 2026) admite la Bot API 10.3, y nuestro bot inicial para Node.js lo usa. Cámbiate cuando necesites algo más nuevo de lo que ofrece Telegraf.

Mi bot de Telegraf se detuvo con 409: Conflict. ¿Qué hago?

Otra copia está haciendo polling con el mismo token, a menudo en tu PC o en tu host anterior. Telegraf se detiene en lugar de reintentar. El panel lo vuelve a iniciar en aproximadamente un minuto; si se detiene otra vez en el minuto siguiente, queda detenido. Busca y detén la otra copia, o crea un token nuevo en @BotFather y pégalo con Reemplazar token.

¿Puedo ejecutar Telegraf con Bun?

Sí. Al hacer el pedido, elige Bun en lugar de Node.js: nuestra página de alojamiento para bots de Telegram incluye Telegraf para él. Los pasos de esta página son para Node.js.

¿Listo para ejecutar tu bot de Telegraf todo el día? Mira los planes en alojamiento para bots de Telegram.