Cómo alojar un bot de node-telegram-bot-api 24/7

Para alojar un bot de node-telegram-bot-api 24/7 lo ejecutas en una máquina que siempre está encendida: un VPS Linux con un servicio de systemd que lo vuelve a iniciar cuando se detiene, o un plan de bots en PlayNHost (desde US$1.99 al mes), donde el panel instala tus paquetes, da el token a tu código y vuelve a iniciar el bot si se cae. En nuestra prueba, un bot con node-telegram-bot-api 2.3.0 usó unos 63 MB de memoria en Node.js 22. Una cosa antes: la versión 2, la que npm instala hoy, es una biblioteca nueva sin la clase TelegramBot, así que los tutoriales escritos para versiones anteriores ya no encajan. Los bots escritos para 0.x o 1.x conservan su API si fijas su versión, como se muestra abajo. Los pasos en PlayNHost:

1. En alojamiento de bots de Telegram, haz clic en Crear servidor en un plan. En la ventana del pedido, responde a ¿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 Conectar, comprueba el nombre del bot que aparece y haz clic en Sí, continuar.
4. Comprueba que tu package.json indica la versión para la que está escrito tu código: ^2.3.0 para un bot con new Bot(...), o la versión antigua para un bot con new TelegramBot(...).
5. En Tu código, haz clic en Subir archivos y sube tu package.json y index.js sin node_modules, o haz clic en Conectar Git.
6. 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.
7. Haz clic en Iniciar bot y abre Console. npm instala la biblioteca 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.
8. 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 node-telegram-bot-api en sí: sus versiones, qué usa en un servidor y qué debes saber antes de alojarlo.

¿Para qué versión está escrito tu bot?

El nombre del paquete siguió igual, pero su API cambió por completo en agosto de 2026:

El README del proyecto lo dice claro: "v2 is a from-scratch redesign, no v1 compatibility", y su changelog dice que npm install node-telegram-bot-api desde un tutorial antiguo "now lands you on a completely different API". Un bot con TelegramBot iniciado con 2.x falla de inmediato, porque la clase ya no existe.

Para un bot escrito para 0.x, deja esa versión en package.json:

"dependencies": {
  "node-telegram-bot-api": "^0.67.0"
}

Un rango con ^ nunca salta a una versión mayor nueva, así que la instalación diaria de paquetes en nuestros servidores mantiene tu bot en 0.x. No escribas latest ni *. Si lo instalas en su lugar desde Paquetes en el panel Código, escribe también la versión, node-telegram-bot-api@0.67: un nombre sin versión pide a npm la versión etiquetada como latest, que es la 2.3.0.

Lo que medimos

Cómo: en nuestro propio nodo, en un contenedor desechable configurado como un plan de bots 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 el arranque hasta la respuesta, y cada cifra es la mediana de las ejecuciones 2 a 4. Medimos la versión 2; la 0.x no se midió.

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

Un bot mínimo con node-telegram-bot-api 2

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

package.json

{
  "name": "my-telegram-bot",
  "private": true,
  "main": "index.js",
  "dependencies": {
    "node-telegram-bot-api": "^2.3.0"
  }
}

index.js

const { Bot, TelegramApiError } = require("node-telegram-bot-api");
const { run } = require("node-telegram-bot-api/node");

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

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

async function main() {
  await bot.init(); // asks Telegram who the bot is, so a wrong token fails here
  await bot.api.deleteWebhook(); // version 2 does not remove a webhook by itself
  console.log(`Logged in as @${bot.botInfo.username}`);
  await run(bot); // polls for messages until the bot is stopped
}

main().catch((err) => {
  if (err instanceof TelegramApiError && err.errorCode === 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);
});

Los ejemplos de la biblioteca leen process.env.BOT_TOKEN. El panel da a tu código el token como TELEGRAM_BOT_TOKEN y también como BOT_TOKEN, TOKEN, TELEGRAM_TOKEN y TELOXIDE_TOKEN, así que esos ejemplos se ejecutan sin cambios. run() viene de node-telegram-bot-api/node: hace polling y se detiene limpiamente con SIGINT o SIGTERM. La versión 2 funciona con require como arriba o con import.

Si el token es incorrecto

En nuestra prueba, con un token falso, la primera llamada de la versión 2 a Telegram (getMe) falló con este error:

TelegramApiError: 401: Unauthorized

La versión 2 no reintenta un token rechazado: bot.init() falla de inmediato. El bot de arriba captura ese caso 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 arreglarlo, en @BotFather envía /mybots, elige tu bot, luego API Token, y copia el token de nuevo. En la página Bot, panel Telegram, haz clic en Reemplazar token, pégalo, haz clic en Guardar token y luego en Reiniciar ahora.

Un bot 0.x se comporta de otra forma: no se detiene. Registra una línea como error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} y vuelve a preguntar a Telegram cada 0,3 segundos aproximadamente, así que parece estar en marcha mientras nada responde. El panel lee esa línea y muestra el mismo aviso.

Qué debes saber de node-telegram-bot-api en un servidor

• Un webhook que quedó en el bot: la versión 2 no lo quita. Su polling trata el 409 como un conflicto, reintenta 10 veces, con 5 segundos entre intentos, y luego se detiene. El bot de arriba llama a bot.api.deleteWebhook() antes de hacer polling; también puedes hacer clic en Quitar webhook en el panel Telegram. La versión 0.x quita un webhook por sí sola cuando el polling encuentra un 409.
• Otra copia del bot: ante un 409 Conflict, la versión 2 espera 5 segundos y vuelve a intentarlo, en silencio, hasta 10 veces seguidas. Después se detiene, run() imprime node-telegram-bot-api: polling stopped on a fatal error: con el texto de Telegram, y el panel muestra Tu bot también se está ejecutando en otro sitio. Detén la copia de tu PC o de tu antiguo alojamiento. Consulta Solucionar el error 409 Conflict de un bot de Telegram.
• Un error en un comando no detiene el bot. La versión 2 imprime Unhandled error while processing update con el error y sigue. Define tu propio manejador con bot.catch((err, ctx) => ...).
• Webhooks: startWebhook, createWebhookServer y webhookCallback necesitan una dirección HTTPS pública, que estos planes todavía no incluyen. Usa run(bot) o bot.startPolling(). Si vienes de un alojamiento con webhook: Cómo mover un bot de Telegram a PlayNHost.
• Ver qué hace: en la página Bot, panel Entorno, añade la variable DEBUG con el valor node-telegram-bot-api:* (Añadir variable) y reinicia. La versión 2 registra entonces cada petición y cada poll en la consola.
• Versión de Node.js: la 2.3.0 necesita Node.js 18.2 o más reciente. 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 pone NODE_OPTIONS=--max-old-space-size al 80 por ciento de la memoria de tu plan, para que el resto del proceso tenga 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

La versión 2 necesita Node.js 18.2 o más reciente. En Debian 12 o 13, o en Ubuntu 24.04, el paquete de la distribución es lo bastante nuevo (Debian 12 incluye Node.js 18.20, Debian 13 incluye 20.19, Ubuntu 24.04 incluye 18.19); Ubuntu 22.04 incluye Node.js 12, demasiado antiguo para ella:

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=node-telegram-bot-api 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 run() convierte en una parada limpia. Detén antes cualquier otra copia, o Telegram responderá a ambas con 409 Conflict.

Alojamiento propio o plan de 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 después de cada cambio, el archivo del servicio, el archivo del token y sus permisos.
• Leer journalctl para saber por qué se detuvo el bot.
• Las copias de seguridad de los datos del bot.

A cambio, un VPS ejecuta cualquier cosa, y puedes darle un dominio con HTTPS para un webhook.

En un plan de bots de PlayNHost, el panel lo hace 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, comprobado con Telegram antes de guardarlo, almacenado cifrado y entregado a tu código.
• Volver a iniciar el bot tras una caída. Si se cae otra vez en un minuto, se queda detenido y Console explica por qué.
• Avisos encima de Console que nombran la causa cuando Telegram rechaza el token, hay otra copia en marcha o hay un webhook configurado, 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

Mi bot antiguo se detuvo con un error como TelegramBot is not a constructor. ¿Por qué?

Lo más probable es que npm instalara la versión 2, que no tiene la clase TelegramBot: require('node-telegram-bot-api') ahora devuelve un objeto con exportaciones con nombre como Bot, no una clase a la que puedas llamar con new. Pon en package.json la versión para la que se escribió tu bot, por ejemplo "node-telegram-bot-api": "^0.67.0", borra node_modules y package-lock.json en Files y reinicia: los paquetes se instalan de nuevo. O pasa el código a la versión 2 con la tabla del changelog del proyecto.

¿Debo escribir un bot nuevo con la versión 2 o con la 0.x?

Para un bot nuevo, la versión 2: es la que recibe actualizaciones, y la 2.3.0 admite la Bot API 10.3 de Telegram. Mantén la 0.x para un bot existente hasta que tengas tiempo de migrarlo; todavía se instala desde npm.

¿Dónde sobreviven las sesiones a un reinicio?

No en MemorySessionStorage: vive en el proceso y queda vacío tras cada reinicio. FileSessionStorage de node-telegram-bot-api/node escribe un archivo por chat en una carpeta que tú nombras, por ejemplo ./.my_bot_sessions. En nuestros planes esa carpeta está en los archivos de tu servidor, así que sobrevive a los reinicios y está en tus copias de seguridad.

¿Listo para ejecutar tu bot de node-telegram-bot-api a todas horas? Consulta los planes en alojamiento de bots de Telegram.