Come ospitare un bot Telegraf 24/7 (Telegram, Node.js)

Per ospitare un bot Telegraf 24/7 lo fai girare 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 Telegraf 4.16.3 ha usato circa 60 MB di memoria su Node.js 22. bot.launch() di Telegraf usa il long polling di default, ed è ciò che servono ai nostri piani: non hanno ancora un indirizzo HTTPS pubblico per un webhook. 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. In Il tuo codice, clicca su Carica i file e carica il tuo package.json e il tuo index.js senza node_modules, oppure clicca su Collega Git.
5. Nella pagina Bot, riquadro Codice, controlla che File di avvio sia il file che avvia il tuo bot (index.js di default). Clicca su Salva se lo cambi.
6. Clicca su Avvia il bot e apri Console. Al primo avvio npm installa Telegraf, poi il tuo bot stampa Logged in as @your_bot e l’indicatore in Panoramica passa a Online su Telegram.
7. 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 nel pannello sono spiegati in Come ospitare un bot Telegram. Questa pagina parla di Telegraf in sé: cosa usa su un server e cosa sapere prima di ospitarlo.

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 percento), 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.

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

Un bot Telegraf minimo

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-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"));

Gli esempi di Telegraf 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. La riga Logged in as @your_bot è ciò che fa passare l’indicatore a Online su Telegram.

Se il token è sbagliato

Nel nostro test, con un token falso, bot.launch() di Telegraf è fallito con un TelegramError il cui err.code è 401. Stampato come nome e messaggio, appare così:

Error: 401: Unauthorized

Il nome compare come Error perché la classe di errore di Telegraf non imposta un nome proprio. Telegraf non riprova con un token rifiutato: bot.launch() fallisce subito, così come con un bot che non ha ricevuto alcun token (401: Bot Token is required). Il bot qui sopra intercetta entrambi i casi 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 e poi su Riavvia ora.

Cosa sapere su Telegraf su un server

• Rilasci: l’ultimo Telegraf è la 4.16.3, rilasciata il 29 feb 2024. La 4.16.0 (25 feb 2024) ha aggiunto le Bot API 7.0 e 7.1 di Telegram; il changelog di Telegram è arrivato alla Bot API 10.3 (24 ago 2026). Il repository GitHub ha ricevuto l’ultimo push il 24 set 2026. Nel nostro test la 4.16.3 si è installata e avviata normalmente su Node.js 22.
• La riga di pronto va nel callback di launch(). bot.launch() ritorna solo quando il bot si ferma, quindi un console.log dopo await bot.launch() non viene mai stampato finché il bot gira. Dalla 4.16.0 launch() accetta un callback che Telegraf chiama quando Telegram ha accettato il token, con bot.botInfo già compilato.
• Un errore in un comando ferma il bot se non imposti bot.catch. Il gestore predefinito di Telegraf stampa Unhandled error while processing con l’aggiornamento e rilancia l’errore, il che termina il polling, quindi il processo si ferma. Il nostro pannello riavvia un bot andato in crash entro circa un minuto, ma fino ad allora è offline. Con bot.catch, come sopra, l’errore viene stampato e il bot va avanti.
• Ogni aggiornamento ha 90 secondi. Un aggiornamento i cui gestori impiegano di più viene segnalato come errore (l’opzione handlerTimeout, 90.000 ms di default), che passa poi a bot.catch. Passa new Telegraf(token, { handlerTimeout: ... }) per i lavori più lunghi.
• Un webhook rimasto sul bot viene rimosso per te. bot.launch() senza l’opzione webhook chiama deleteWebhook prima di avviare il polling e mantiene i messaggi in attesa, a meno che tu non passi dropPendingUpdates: true. bot.launch({ webhook: ... }) richiede un indirizzo HTTPS pubblico, che questi piani non includono ancora: usa il semplice bot.launch(). Se vieni da un host con webhook: Come spostare un bot Telegram su PlayNHost.
• Un’altra copia del bot ferma questa. Con 409 Conflict (lo stesso token in polling altrove) il polling di Telegraf lancia un errore invece di riprovare. 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. Durante il polling, gli errori di rete, 429 e gli errori 5xx di Telegram vengono ritentati dopo l’attesa richiesta da Telegram, oppure 5 secondi.
• Versione di Node.js: Telegraf 4.16.3 richiede Node.js 12.20 o 14.13.1 e successivi. 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 percento della memoria del tuo piano, così al resto del processo resta spazio. Dettagli sullo script di avvio di Node.js: Come ospitare un bot Discord Node.js.

Ospitarlo da solo su un VPS Linux

Su Debian 12 o 13, oppure Ubuntu 24.04, il pacchetto della distribuzione basta per Telegraf (Debian 12 include Node.js 18.20, Debian 13 include 20.19, Ubuntu 24.04 include 18.19):

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 leggibile solo da root:

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

Avvialo subito e a ogni avvio del sistema, 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 le righe process.once trasformano in bot.stop(). Ferma prima qualsiasi altra copia, altrimenti Telegram risponde a entrambe con 409 Conflict.

Da solo o con un piano bot

Su un VPS che gestisci tu, ti occupi di:

• Aggiornamenti e sicurezza del sistema operativo, e upgrade di Node.js.
• Eseguire npm install dopo ogni modifica, il file di 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, controllato 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 indica il motivo.
• Banner sopra Console che indicano la causa quando Telegram rifiuta il token, è in esecuzione un’altra copia o è impostato un webhook, con un pulsante Rimuovi il webhook nel riquadro Telegram.
• Caricamento file, deploy Git e backup dal pannello.

Domande frequenti

Perché non viene stampato nulla dopo await bot.launch()?

Perché bot.launch() aspetta che il polling finisca, e il polling dura quanto il bot. Il codice dopo viene eseguito solo quando il bot si ferma. Metti i messaggi di avvio nel callback, bot.launch(() => ...), e registra i comandi prima di chiamare launch().

Posso continuare a usare Telegraf o devo passare a grammY?

Un bot Telegraf 4 funzionante gira sui nostri piani così com’è: non c’è nulla da cambiare per ospitarlo. Il suo ultimo rilascio è di febbraio 2024, quindi i metodi aggiunti da Telegram dopo la Bot API 7.1 non hanno una scorciatoia in Telegraf. grammY 1.46.0 (26 ago 2026) supporta la Bot API 10.3, e il nostro bot di partenza per Node.js lo usa. Passa quando ti serve qualcosa di più recente di ciò che offre Telegraf.

Il mio bot Telegraf si è fermato con 409: Conflict. E ora?

Un’altra copia sta facendo polling con lo stesso token, spesso sul tuo PC o sul vecchio host. Telegraf si ferma invece di riprovare. Il pannello lo riavvia entro circa un minuto; se si ferma di nuovo entro un minuto da allora, resta fermo. Trova e ferma l’altra copia, oppure crea un nuovo token in @BotFather e incollalo con Sostituisci il token.

Posso usare Telegraf con Bun?

Sì. Quando ordini, scegli Bun invece di Node.js: la nostra pagina di hosting per bot Telegram include Telegraf per Bun. I passi di questa pagina sono per Node.js.

Pronto a far girare il tuo bot Telegraf giorno e notte? Guarda i piani su hosting per bot Telegram.