Comment héberger un bot Telegraf 24/7 (Telegram, Node.js)

Pour héberger un bot Telegraf 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 une offre 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 Telegraf 4.16.3 a utilisé environ 60 Mo de mémoire sous Node.js 22. bot.launch() de Telegraf utilise le long polling par défaut, ce dont nos offres ont besoin : elles n’ont pas encore d’adresse HTTPS publique pour un webhook. Les étapes chez PlayNHost :

1. Sur l’hébergement de bots Telegram, cliquez sur Créer un serveur pour une offre. 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. À l’étape Connexion à Telegram, collez le token de @BotFather sous Collez le token de votre bot, cliquez sur Connexion, vérifiez le nom du bot affiché et cliquez sur Oui, continuer.
4. À l’étape Votre code, cliquez sur Téléverser des fichiers et envoyez votre package.json et votre index.js sans node_modules, ou cliquez sur Connecter Git.
5. 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.
6. Cliquez sur Démarrer le bot et ouvrez Console. npm installe Telegraf au premier démarrage, puis votre bot affiche Logged in as @your_bot et la pastille de Aperçu passe à En ligne sur Telegram.
7. 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 détaillées dans Comment héberger un bot Telegram. Cette page parle de Telegraf lui-même : ce qu’il utilise sur un serveur et ce qu’il faut savoir avant de l’héberger.

Ce que nous avons mesuré

Méthode : sur notre propre node, dans un conteneur jetable configuré comme une offre 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 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 va du lancement à la réponse, et chaque valeur est la médiane des exécutions 2 à 4.

Ce sont des planchers : un bot sans conversations et sans données. 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 qu’une petite part des 0,5 Go de l’offre STARTER.

Un bot Telegraf minimal

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

Les exemples de Telegraf 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 modification. La ligne Logged in as @your_bot est ce qui fait passer la pastille à En ligne sur Telegram.

Si le token est incorrect

Dans notre test, avec un faux token, bot.launch() de Telegraf a échoué avec une TelegramError dont err.code vaut 401. Affichée sous la forme nom et message, elle donne :

Error: 401: Unauthorized

Le nom s’affiche comme Error parce que la classe d’erreur de Telegraf ne définit pas de nom propre. Telegraf ne retente pas un token refusé : bot.launch() échoue aussitôt, tout comme pour un bot qui n’a reçu aucun token (401: Bot Token is required). Le bot ci-dessus intercepte les deux 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 à 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.

Ce qu’il faut savoir sur Telegraf sur un serveur

• Versions : la dernière version de Telegraf est la 4.16.3, publiée le 29 févr. 2024. La 4.16.0 (25 févr. 2024) a ajouté les Bot API 7.0 et 7.1 de Telegram ; le journal des modifications de Telegram en est à la Bot API 10.3 (24 août 2026). Le dépôt GitHub a reçu son dernier push le 24 sept. 2026. Dans notre test, la 4.16.3 s’est installée et lancée normalement sous Node.js 22.
• La ligne de démarrage va dans le callback de launch(). bot.launch() ne rend la main que lorsque le bot s’arrête, donc un console.log après await bot.launch() ne s’affiche jamais tant qu’il tourne. Depuis la 4.16.0, launch() accepte un callback que Telegraf appelle une fois que Telegram a accepté le token, avec bot.botInfo rempli.
• Une erreur dans une commande arrête le bot si vous ne définissez pas bot.catch. Le gestionnaire par défaut de Telegraf affiche Unhandled error while processing avec la mise à jour et relance l’erreur, ce qui met fin au polling, donc le processus s’arrête. Notre panel relance un bot planté en moins d’une minute environ, mais il est hors ligne d’ici là. Avec bot.catch, comme ci-dessus, l’erreur est affichée et le bot continue.
• Chaque mise à jour dispose de 90 secondes. Une mise à jour dont les gestionnaires prennent plus de temps est signalée comme une erreur (l’option handlerTimeout, 90.000 ms par défaut), qui va alors à bot.catch. Passez new Telegraf(token, { handlerTimeout: ... }) pour les tâches plus longues.
• Un webhook resté sur le bot est supprimé pour vous. bot.launch() sans l’option webhook appelle deleteWebhook avant de lancer le polling, et conserve les messages en attente sauf si vous passez dropPendingUpdates: true. bot.launch({ webhook: ... }) nécessite une adresse HTTPS publique, que ces offres n’incluent pas encore : utilisez bot.launch() simple. Pour quitter un hébergeur à webhook : Comment déplacer un bot Telegram vers PlayNHost.
• Une autre copie du bot arrête celle-ci. Avec 409 Conflict (le même token en polling ailleurs), le polling de Telegraf lève une erreur au lieu de réessayer. Le panel affiche Votre bot tourne aussi ailleurs : arrêtez la copie sur votre PC ou chez votre ancien hébergeur. Voir Corriger l’erreur 409 Conflict d’un bot Telegram. Pendant le polling, les erreurs réseau, 429 et les erreurs 5xx de Telegram sont retentées après l’attente demandée par Telegram, ou 5 secondes.
• Version de Node.js : Telegraf 4.16.3 demande Node.js 12.20 ou 14.13.1 et plus récent. Le Runtime du volet Code propose Node.js 20, 22 (recommended), 24, 25 et 26.
• Limite mémoire : le script de démarrage règle NODE_OPTIONS=--max-old-space-size à 80 pour cent de la mémoire de votre offre, 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

Sous Debian 12 ou 13, ou Ubuntu 24.04, le paquet de la distribution suffit pour Telegraf (Debian 12 fournit Node.js 18.20, Debian 13 fournit 20.19, Ubuntu 24.04 fournit 18.19) :

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=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

Démarrez-le maintenant et à chaque démarrage, 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 les lignes process.once transforment en bot.stop(). Arrêtez d’abord toute autre copie, sinon Telegram répond aux deux par 409 Conflict.

Auto-hébergement ou offre 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 contrepartie, un VPS exécute n’importe quoi, et vous pouvez lui donner un domaine avec HTTPS pour un webhook.

Sur une offre 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 changent.
• Le token, vérifié auprès de Telegram avant d’être enregistré, stocké chiffré et donné à 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.
• Envoi de fichiers, déploiements Git et sauvegardes depuis le panel.

Questions fréquentes

Pourquoi rien ne s’affiche après await bot.launch() ?

Parce que bot.launch() attend la fin du polling, et le polling dure aussi longtemps que le bot. Le code placé après ne s’exécute que lorsque le bot s’arrête. Mettez les messages de démarrage dans le callback, bot.launch(() => ...), et enregistrez les commandes avant d’appeler launch().

Puis-je continuer avec Telegraf, ou passer à grammY ?

Un bot Telegraf 4 qui fonctionne tourne tel quel sur nos offres : il n’y a rien à changer pour l’héberger. Sa dernière version date de février 2024, donc les méthodes ajoutées par Telegram après la Bot API 7.1 n’ont pas de raccourci Telegraf. grammY 1.46.0 (26 août 2026) prend en charge la Bot API 10.3, et notre bot de démarrage pour Node.js l’utilise. Changez quand vous avez besoin de quelque chose de plus récent que ce que Telegraf offre.

Mon bot Telegraf s’est arrêté avec 409: Conflict. Que faire ?

Une autre copie fait du polling avec le même token, souvent sur votre PC ou chez votre ancien hébergeur. Telegraf s’arrête au lieu de réessayer. Le panel le relance en moins d’une minute environ ; s’il s’arrête à nouveau dans la minute qui suit, il reste arrêté. Trouvez et arrêtez l’autre copie, ou créez un nouveau token dans @BotFather et collez-le avec Remplacer le token.

Puis-je faire tourner Telegraf sur Bun ?

Oui. Au moment de commander, choisissez Bun au lieu de Node.js : notre page d’hébergement de bots Telegram y référence Telegraf. Les étapes de cette page concernent Node.js.

Prêt à faire tourner votre bot Telegraf jour et nuit ? Découvrez les offres sur l’hébergement de bots Telegram.