Come ospitare un bot node-telegram-bot-api 24/7

Per ospitare un bot node-telegram-bot-api 24/7 lo esegui su una macchina sempre accesa: un VPS Linux con un servizio systemd che lo riavvia quando si ferma, oppure un piano bot su PlayNHost (da 1,99 US$ al mese), dove il pannello installa i tuoi pacchetti, dà il token al tuo codice e riavvia il bot se va in crash. Nel nostro test un bot con node-telegram-bot-api 2.3.0 ha usato circa 63 MB di memoria su Node.js 22. Una cosa prima di tutto: la versione 2, quella che npm installa oggi, è una libreria nuova senza la classe TelegramBot, quindi i tutorial scritti per le versioni precedenti non corrispondono più. I bot scritti per 0.x o 1.x mantengono la loro API se blocchi la versione, come mostrato sotto. I passi su PlayNHost:

1. Su hosting per bot Telegram, clicca su Crea server su un piano. Nella finestra dell’ordine, rispondi a Per quale piattaforma è il tuo bot? con Telegram e scegli Node.js.
2. Apri il tuo server nel pannello. La scheda Configura il tuo bot in Panoramica si apre su Connetti a Telegram; il suo primo passaggio, Cosa viene eseguito, dovrebbe dire Questo bot esegue Node.js Bot.
3. In Connetti a Telegram, incolla il token di @BotFather sotto Incolla il token del bot, clicca su Connessione, controlla il nome del bot mostrato e clicca su Sì, continua.
4. Controlla che il tuo package.json indichi la versione per cui è scritto il tuo codice: ^2.3.0 per un bot con new Bot(...), oppure la vecchia versione per un bot con new TelegramBot(...).
5. In Il tuo codice, clicca su Carica i file e carica il tuo package.json e index.js senza node_modules, oppure clicca su Collega Git.
6. Nella pagina Bot, riquadro Codice, controlla che File di avvio sia il file che avvia il tuo bot (index.js per impostazione predefinita). Clicca su Salva se lo cambi.
7. Clicca su Avvia il bot e apri Console. npm installa la libreria al primo avvio, poi il tuo bot stampa Logged in as @your_bot e l’indicatore in Panoramica passa a Online su Telegram.
8. Nella pagina Bot, riquadro Telegram, clicca su Apri in Telegram e invia /start al tuo bot.

La creazione del bot in @BotFather e i passi del pannello sono spiegati in Come ospitare un bot Telegram. Questa pagina riguarda node-telegram-bot-api in sé: le sue versioni, cosa usa su un server e cosa sapere prima di ospitarlo.

Per quale versione è scritto il tuo bot?

Il nome del pacchetto è rimasto lo stesso, ma la sua API è cambiata completamente ad agosto 2026:

Il README del progetto lo dice chiaramente: "v2 is a from-scratch redesign, no v1 compatibility", e il suo changelog dice che npm install node-telegram-bot-api eseguito da un vecchio tutorial "now lands you on a completely different API". Un bot TelegramBot avviato con la 2.x fallisce subito, perché la classe non esiste più.

Per un bot scritto per 0.x, tieni quella versione in package.json:

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

Un intervallo con ^ non passa mai a una nuova versione maggiore, quindi l’installazione quotidiana dei pacchetti sui nostri server mantiene il tuo bot sulla 0.x. Non scrivere latest né *. Se invece lo installi da Pacchetti nel riquadro Codice, scrivi anche la versione, node-telegram-bot-api@0.67: un nome senza versione chiede a npm la release con il tag latest, che è la 2.3.0.

Cosa abbiamo misurato

Come: sul nostro nodo, in un container usa e getta configurato come un piano bot da 1 GB (l’immagine Node.js 22 e il comando di avvio del nostro tipo di bot Node.js, con il limite di memoria di Node all’80 per cento), ogni bot ha chiamato Telegram con un token falso, che Telegram ha rifiutato. La memoria è quella residente 15 secondi dopo quella risposta, il tempo di avvio va dal lancio alla risposta e ogni valore è la mediana delle esecuzioni da 2 a 4. Abbiamo misurato la versione 2; la 0.x non è stata misurata.

Sono valori minimi: un bot senza chat e senza dati. Il tuo codice, ciò che tiene in memoria e il numero di chat si sommano, quindi la libreria è una piccola parte del piano STARTER da 0,5 GB.

Un bot minimo con node-telegram-bot-api 2

Risponde a /start, legge il token che gli dà il pannello e stampa una riga di pronto. Metti entrambi i file nella cartella principale del tuo 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);
});

Gli esempi della libreria leggono process.env.BOT_TOKEN. Il pannello dà il token al tuo codice come TELEGRAM_BOT_TOKEN e anche come BOT_TOKEN, TOKEN, TELEGRAM_TOKEN e TELOXIDE_TOKEN, quindi quegli esempi funzionano senza modifiche. run() viene da node-telegram-bot-api/node: fa polling e si ferma in modo pulito con SIGINT o SIGTERM. La versione 2 funziona con require come sopra o con import.

Se il token è sbagliato

Nel nostro test, con un token falso, la prima chiamata della versione 2 a Telegram (getMe) è fallita con questo errore:

TelegramApiError: 401: Unauthorized

La versione 2 non riprova con un token rifiutato: bot.init() fallisce subito. Il bot qui sopra intercetta quel caso e stampa invece Telegram did not accept the bot token. Paste the current one from @BotFather, then restart., e il pannello mostra il banner Telegram non ha accettato il token del bot sopra Console. Per risolvere, in @BotFather invia /mybots, scegli il tuo bot, poi API Token, e copia di nuovo il token. Nella pagina Bot, riquadro Telegram, clicca su Sostituisci il token, incollalo, clicca su Salva il token, poi su Riavvia ora.

Un bot 0.x si comporta diversamente: non si ferma. Registra una riga come error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} e richiede a Telegram circa ogni 0,3 secondi, quindi sembra in esecuzione mentre nulla risponde. Il pannello legge quella riga e mostra lo stesso banner.

Cosa sapere su node-telegram-bot-api su un server

• Un webhook rimasto sul bot: la versione 2 non lo rimuove. Il suo polling tratta il 409 come un conflitto, riprova 10 volte, a 5 secondi di distanza, poi si ferma. Il bot qui sopra chiama bot.api.deleteWebhook() prima di fare polling; puoi anche cliccare su Rimuovi il webhook nel riquadro Telegram. La versione 0.x rimuove da sola un webhook quando il polling incontra un 409.
• Un’altra copia del bot: su un 409 Conflict la versione 2 aspetta 5 secondi e riprova, in silenzio, fino a 10 volte di fila. Dopo si ferma, run() stampa node-telegram-bot-api: polling stopped on a fatal error: con il testo di Telegram, e il pannello mostra Il tuo bot è in esecuzione anche altrove. Ferma la copia sul tuo PC o sul vecchio host. Vedi Come risolvere l’errore 409 Conflict di un bot Telegram.
• Un errore in un comando non ferma il bot. La versione 2 stampa Unhandled error while processing update con l’errore e va avanti. Imposta il tuo gestore con bot.catch((err, ctx) => ...).
• Webhook: startWebhook, createWebhookServer e webhookCallback richiedono un indirizzo HTTPS pubblico, che questi piani non includono ancora. Usa run(bot) o bot.startPolling(). Se arrivi da un host con webhook: Come spostare un bot Telegram su PlayNHost.
• Vedere cosa fa: nella pagina Bot, riquadro Ambiente, aggiungi la variabile DEBUG con il valore node-telegram-bot-api:* (Aggiungi variabile) e riavvia. La versione 2 registra allora ogni richiesta e ogni poll nella console.
• Versione di Node.js: la 2.3.0 richiede Node.js 18.2 o più recente. Il Runtime nel riquadro Codice offre Node.js 20, 22 (recommended), 24, 25 e 26.
• Limite di memoria: lo script di avvio imposta NODE_OPTIONS=--max-old-space-size all’80 per cento della memoria del tuo piano, così il resto del processo ha spazio. Dettagli sullo script di avvio di Node.js: Come ospitare un bot Discord Node.js.

Ospitarlo da solo su un VPS Linux

La versione 2 richiede Node.js 18.2 o più recente. Su Debian 12 o 13, o Ubuntu 24.04, il pacchetto della distribuzione è abbastanza recente (Debian 12 include Node.js 18.20, Debian 13 include 20.19, Ubuntu 24.04 include 18.19); Ubuntu 22.04 include Node.js 12, troppo vecchio per essa:

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

Crea un utente per il bot, copia i tuoi file e installa i pacchetti:

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

Tieni il token fuori dal tuo codice, in un file che solo root può leggere:

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

Avvialo ora e a ogni avvio della macchina, poi segui il suo output:

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

Restart=always riavvia il bot dopo un crash o un process.exit(1). systemctl stop mybot invia SIGTERM, che run() trasforma in un arresto pulito. Ferma prima qualsiasi altra copia, altrimenti Telegram risponde a entrambe con 409 Conflict.

Self-hosting o piano bot

Su un VPS che gestisci tu, ti occupi di:

• Aggiornamenti e sicurezza del sistema operativo, e gli upgrade di Node.js.
• Eseguire npm install dopo ogni modifica, il file del servizio, il file del token e i suoi permessi.
• Leggere journalctl per capire perché il bot si è fermato.
• I backup dei dati del bot.

In cambio un VPS esegue qualsiasi cosa, e puoi dargli un dominio con HTTPS per un webhook.

Su un piano bot PlayNHost il pannello fa tutto questo per te:

• Un selettore della versione di Node.js e npm install quando cambiano package.json, il file di lock o la versione di Node.js.
• Il token, verificato con Telegram prima di essere salvato, conservato cifrato e dato al tuo codice.
• Il riavvio del bot dopo un crash. Se va in crash di nuovo entro un minuto, resta fermo e Console ne dice il motivo.
• Banner sopra Console che indicano la causa quando Telegram rifiuta il token, è in esecuzione un’altra copia o c’è un webhook impostato, con un pulsante Rimuovi il webhook nel riquadro Telegram.
• Upload, deploy Git e backup dal pannello.

Domande frequenti

Il mio vecchio bot si è fermato con un errore come TelegramBot is not a constructor. Perché?

Molto probabilmente npm ha installato la versione 2, che non ha la classe TelegramBot: require('node-telegram-bot-api') ora restituisce un oggetto di export con nome come Bot, non una classe che puoi chiamare con new. Metti in package.json la versione per cui è stato scritto il tuo bot, per esempio "node-telegram-bot-api": "^0.67.0", elimina node_modules e package-lock.json in Files e riavvia: i pacchetti vengono installati di nuovo. Oppure porta il codice alla versione 2 con la tabella nel changelog del progetto.

Devo scrivere un nuovo bot sulla versione 2 o sulla 0.x?

Per un nuovo bot, la versione 2: è quella che riceve aggiornamenti, e la 2.3.0 supporta la Bot API 10.3 di Telegram. Tieni la 0.x per un bot esistente finché non hai tempo di migrarlo; si installa ancora da npm.

Dove sopravvivono le sessioni a un riavvio?

Non in MemorySessionStorage: vive nel processo ed è vuoto dopo ogni riavvio. FileSessionStorage da node-telegram-bot-api/node scrive un file per chat in una cartella che scegli tu, per esempio ./.my_bot_sessions. Sui nostri piani quella cartella è nei file del tuo server, quindi sopravvive ai riavvii ed è nei tuoi backup.

Pronto a far girare il tuo bot node-telegram-bot-api a tutte le ore? Guarda i piani su hosting per bot Telegram.