Comment héberger un bot node-telegram-bot-api 24/7

Pour héberger un bot node-telegram-bot-api 24/7, vous le faites tourner sur une machine toujours allumée : un VPS Linux avec un service systemd qui le relance quand il s’arrête, ou un forfait bot chez PlayNHost (à partir de 1,99 $US par mois), où le panel installe vos paquets, donne le token à votre code et relance le bot s’il plante. Dans notre test, un bot node-telegram-bot-api 2.3.0 a utilisé environ 63 Mo de mémoire sous Node.js 22. Une chose d’abord : la version 2, celle que npm installe aujourd’hui, est une nouvelle bibliothèque sans classe TelegramBot, donc les tutoriels écrits pour les versions précédentes ne correspondent plus. Les bots écrits pour 0.x ou 1.x gardent leur API si vous figez leur version, comme montré plus bas. Les étapes chez PlayNHost :

1. Sur l’hébergement de bots Telegram, cliquez sur Créer un serveur sur un forfait. Dans la fenêtre de commande, répondez à Pour quelle plateforme est votre bot ? par Telegram et choisissez Node.js.
2. Ouvrez votre serveur dans le panel. La carte Configurer votre bot de la page Aperçu s’ouvre sur Connexion à Telegram ; sa première étape, Ce qui tourne, doit indiquer Ce bot fait tourner Node.js Bot.
3. Sous Connexion à Telegram, collez le token de @BotFather dans Collez le token de votre bot, cliquez sur Connecter, vérifiez le nom du bot affiché et cliquez sur Oui, continuer.
4. Vérifiez que votre package.json indique la version pour laquelle votre code est écrit : ^2.3.0 pour un bot avec new Bot(...), ou l’ancienne version pour un bot avec new TelegramBot(...).
5. Sous Votre code, cliquez sur Téléverser des fichiers et téléversez votre package.json et index.js sans node_modules, ou cliquez sur Connecter Git.
6. Sur la page Bot, volet Code, vérifiez que Fichier d’entrée est le fichier qui démarre votre bot (index.js par défaut). Cliquez sur Enregistrer si vous le changez.
7. Cliquez sur Démarrer le bot et ouvrez Console. npm installe la bibliothèque au premier démarrage, puis votre bot affiche Logged in as @your_bot et la pastille de Aperçu passe à En ligne sur Telegram.
8. Sur la page Bot, volet Telegram, cliquez sur Ouvrir dans Telegram et envoyez /start à votre bot.

La création du bot dans @BotFather et les étapes du panel sont expliquées dans Comment héberger un bot Telegram. Cette page parle de node-telegram-bot-api lui-même : ses versions, ce qu’il utilise sur un serveur et ce qu’il faut savoir avant de l’héberger.

Pour quelle version votre bot est-il écrit ?

Le nom du paquet est resté le même, mais son API a entièrement changé en août 2026 :

Le README du projet le dit clairement : "v2 is a from-scratch redesign, no v1 compatibility", et son changelog explique que npm install node-telegram-bot-api lancé depuis un vieux tutoriel "now lands you on a completely different API". Un bot TelegramBot démarré avec la 2.x échoue immédiatement, car la classe n’existe plus.

Pour un bot écrit pour 0.x, gardez cette version dans package.json :

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

Une plage avec ^ ne passe jamais à une nouvelle version majeure, donc l’installation quotidienne des paquets sur nos serveurs garde votre bot en 0.x. N’écrivez pas latest ni *. Si vous l’installez plutôt via Paquets dans le volet Code, écrivez aussi la version, node-telegram-bot-api@0.67 : un nom sans version demande à npm la version taguée latest, c’est-à-dire la 2.3.0.

Ce que nous avons mesuré

Méthode : sur notre propre nœud, dans un conteneur jetable configuré comme un forfait bot de 1 Go (l’image Node.js 22 et la commande de démarrage de notre type de bot Node.js, avec la limite de mémoire de Node à 80 pour cent), chaque bot a appelé Telegram avec un faux token, que Telegram a refusé. La mémoire est la mémoire résidente 15 secondes après cette réponse, le temps de démarrage court du lancement à la réponse, et chaque valeur est la médiane des exécutions 2 à 4. Nous avons mesuré la version 2 ; la 0.x n’a pas été mesurée.

Ce sont des planchers : un bot sans conversations ni données pour l’instant. Votre propre code, ce qu’il garde en mémoire et le nombre de conversations s’y ajoutent, donc la bibliothèque ne pèse que peu dans le forfait STARTER de 0,5 Go.

Un bot minimal node-telegram-bot-api 2

Il répond à /start, lit le token que lui donne le panel et affiche une ligne de démarrage. Mettez les deux fichiers dans le dossier principal de votre 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);
});

Les exemples de la bibliothèque lisent process.env.BOT_TOKEN. Le panel donne le token à votre code sous le nom TELEGRAM_BOT_TOKEN et aussi sous BOT_TOKEN, TOKEN, TELEGRAM_TOKEN et TELOXIDE_TOKEN, donc ces exemples fonctionnent sans changement. run() vient de node-telegram-bot-api/node : il fait du polling et s’arrête proprement sur SIGINT ou SIGTERM. La version 2 fonctionne avec require comme ci-dessus ou avec import.

Si le token est incorrect

Dans notre test, avec un faux token, le premier appel de la version 2 à Telegram (getMe) a échoué avec cette erreur :

TelegramApiError: 401: Unauthorized

La version 2 ne réessaie pas un token refusé : bot.init() échoue aussitôt. Le bot ci-dessus intercepte ce cas et affiche à la place Telegram did not accept the bot token. Paste the current one from @BotFather, then restart., et le panel affiche la bannière Telegram n’a pas accepté le token de votre bot au-dessus de Console. Pour corriger, dans @BotFather envoyez /mybots, choisissez votre bot, puis API Token, et copiez de nouveau le token. Sur la page Bot, volet Telegram, cliquez sur Remplacer le token, collez-le, cliquez sur Enregistrer le token, puis sur Redémarrer maintenant.

Un bot 0.x se comporte autrement : il ne s’arrête pas. Il journalise une ligne comme error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} et interroge de nouveau Telegram environ toutes les 0,3 secondes, donc il semble tourner alors que rien ne répond. Le panel lit cette ligne et affiche la même bannière.

Ce qu’il faut savoir de node-telegram-bot-api sur un serveur

• Un webhook resté sur le bot : la version 2 ne le retire pas. Son polling traite le 409 comme un conflit, réessaie 10 fois, à 5 secondes d’intervalle, puis s’arrête. Le bot ci-dessus appelle bot.api.deleteWebhook() avant de faire du polling ; vous pouvez aussi cliquer sur Retirer le webhook dans le volet Telegram. La version 0.x retire un webhook toute seule quand le polling rencontre un 409.
• Une autre copie du bot : sur un 409 Conflict, la version 2 attend 5 secondes et réessaie, discrètement, jusqu’à 10 fois de suite. Ensuite elle s’arrête, run() affiche node-telegram-bot-api: polling stopped on a fatal error: avec le texte de Telegram, et le panel affiche Votre bot tourne aussi ailleurs. Arrêtez la copie sur votre PC ou votre ancien hébergeur. Voir Corriger l’erreur 409 Conflict d’un bot Telegram.
• Une erreur dans une commande n’arrête pas le bot. La version 2 affiche Unhandled error while processing update avec l’erreur et continue. Définissez votre propre gestionnaire avec bot.catch((err, ctx) => ...).
• Webhooks : startWebhook, createWebhookServer et webhookCallback exigent une adresse HTTPS publique, que ces forfaits n’incluent pas encore. Utilisez run(bot) ou bot.startPolling(). Pour quitter un hébergeur à webhook : Comment déplacer un bot Telegram vers PlayNHost.
• Voir ce qu’il fait : sur la page Bot, volet Environnement, ajoutez la variable DEBUG avec la valeur node-telegram-bot-api:* (Ajouter la variable) et redémarrez. La version 2 trace alors chaque requête et chaque poll dans la console.
• Version de Node.js : la 2.3.0 exige Node.js 18.2 ou plus récent. Le Runtime du volet Code propose Node.js 20, 22 (recommended), 24, 25 et 26.
• Limite de mémoire : le script de démarrage règle NODE_OPTIONS=--max-old-space-size à 80 pour cent de la mémoire de votre forfait, pour laisser de la place au reste du processus. Détails du script de démarrage Node.js : Comment héberger un bot Discord Node.js.

L’héberger vous-même sur un VPS Linux

La version 2 exige Node.js 18.2 ou plus récent. Sur Debian 12 ou 13, ou Ubuntu 24.04, le paquet de la distribution est assez récent (Debian 12 fournit Node.js 18.20, Debian 13 fournit 20.19, Ubuntu 24.04 fournit 18.19) ; Ubuntu 22.04 fournit Node.js 12, trop ancien pour elle :

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

Créez un utilisateur pour le bot, copiez vos fichiers et installez les paquets :

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

Gardez le token hors de votre code, dans un fichier que seul root peut lire :

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

Créez /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

Démarrez-le maintenant et à chaque démarrage de la machine, puis suivez sa sortie :

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

Restart=always relance le bot après un plantage ou un process.exit(1). systemctl stop mybot envoie SIGTERM, que run() transforme en arrêt propre. Arrêtez d’abord toute autre copie, sinon Telegram répond aux deux par 409 Conflict.

Auto-hébergement ou forfait bot

Sur un VPS que vous gérez vous-même, vous vous occupez de :

• Les mises à jour et la sécurité du système d’exploitation, et les mises à niveau de Node.js.
• Lancer npm install après chaque changement, le fichier de service, le fichier du token et ses permissions.
• Lire journalctl pour savoir pourquoi le bot s’est arrêté.
• Les sauvegardes des données du bot.

En échange, un VPS exécute n’importe quoi, et vous pouvez lui donner un domaine avec HTTPS pour un webhook.

Sur un forfait bot PlayNHost, le panel s’en charge pour vous :

• Un sélecteur de version de Node.js, et npm install quand package.json, le fichier de verrouillage ou la version de Node.js change.
• Le token, vérifié auprès de Telegram avant d’être enregistré, stocké chiffré et transmis à votre code.
• Le redémarrage du bot après un plantage. S’il replante dans la minute, il reste arrêté et Console en donne la raison.
• Des bannières au-dessus de Console qui nomment la cause quand Telegram refuse le token, qu’une autre copie tourne ou qu’un webhook est défini, avec un bouton Retirer le webhook dans le volet Telegram.
• Téléversement, déploiements Git et sauvegardes depuis le panel.

Questions fréquentes

Mon ancien bot s’est arrêté avec une erreur comme TelegramBot is not a constructor. Pourquoi ?

Très probablement, npm a installé la version 2, qui n’a pas de classe TelegramBot : require('node-telegram-bot-api') renvoie maintenant un objet d’exports nommés comme Bot, pas une classe que l’on peut appeler avec new. Mettez dans package.json la version pour laquelle votre bot a été écrit, par exemple "node-telegram-bot-api": "^0.67.0", supprimez node_modules et package-lock.json dans Files, et redémarrez : les paquets s’installent de nouveau. Ou migrez le code vers la version 2 avec le tableau du changelog du projet.

Dois-je écrire un nouveau bot avec la version 2 ou la 0.x ?

Pour un nouveau bot, la version 2 : c’est celle qui reçoit les mises à jour, et la 2.3.0 prend en charge la Bot API 10.3 de Telegram. Gardez la 0.x pour un bot existant jusqu’à ce que vous ayez le temps de migrer ; elle s’installe toujours depuis npm.

Où les sessions survivent-elles à un redémarrage ?

Pas dans MemorySessionStorage : il vit dans le processus et est vide après chaque redémarrage. FileSessionStorage de node-telegram-bot-api/node écrit un fichier par conversation dans un dossier que vous nommez, par exemple ./.my_bot_sessions. Sur nos forfaits, ce dossier se trouve dans les fichiers de votre serveur, donc il survit aux redémarrages et figure dans vos sauvegardes.

Prêt à faire tourner votre bot node-telegram-bot-api jour et nuit ? Voyez les forfaits sur l’hébergement de bots Telegram.