Comment héberger un bot grammY 24/7

Pour héberger un bot grammY 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 panneau installe vos paquets, donne le token à votre code et relance le bot s’il plante. Dans notre test, un bot grammY 1.46.0 a utilisé environ 60 Mo de mémoire sous Node.js 22. bot.start() de grammY utilise le long polling, ce dont nos offres ont besoin : elles n’ont pas encore d’adresse HTTPS publique pour un webhook. Les étapes sur 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. Dans 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. Dans 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. Pas encore de code ? Créer un bot de départ écrit un petit bot grammY pour vous.
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 grammY 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 panneau sont expliquées dans Comment héberger un bot Telegram. Cette page traite de grammY 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 nœud, 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 court du lancement à la réponse, et chaque valeur est la médiane des exécutions 2 à 4.

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

Un bot grammY minimal

Il répond à /start, lit le token que lui donne le panneau et affiche une ligne de démarrage. Mettez les deux fichiers dans le dossier principal de votre bot.

package.json

{
  "name": "my-grammy-bot",
  "private": true,
  "main": "index.js",
  "dependencies": {
    "grammy": "^1.46.0"
  }
}

index.js

const { Bot, GrammyError } = require("grammy");

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

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

// Without this, an error in one command stops the whole bot.
bot.catch((err) => {
  console.error(`Error while handling update ${err.ctx.update.update_id}:`, err.error);
});

// bot.start() only returns when the bot stops, so the ready line goes in onStart.
bot.start({
  onStart: (me) => console.log(`Logged in as @${me.username}`),
}).catch((err) => {
  if (err instanceof GrammyError && err.error_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);
});

Le panneau donne le token à votre code sous le nom TELEGRAM_BOT_TOKEN, mais aussi BOT_TOKEN, TOKEN, TELEGRAM_TOKEN et TELOXIDE_TOKEN, donc process.env.BOT_TOKEN des autres exemples fonctionne aussi. 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.start() de grammY s’est arrêté avec cette erreur :

GrammyError: Call to 'deleteWebhook' failed! (401: Unauthorized)

bot.start() envoie getMe et deleteWebhook en même temps, donc l’erreur nomme l’appel que Telegram a refusé en premier : dans certaines de nos exécutions, c’était Call to 'getMe' failed! (401: Unauthorized). grammY ne réessaie pas un token refusé : bot.start() é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 panneau 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.

Ce qu’il faut savoir sur grammY sur un serveur

• La ligne de démarrage va dans onStart. bot.start() ne rend la main que lorsque le bot s’arrête, donc un console.log placé après await bot.start() ne s’affiche jamais tant qu’il tourne. grammY appelle onStart avec les informations de votre bot juste avant de demander à Telegram les premiers messages.
• Une erreur dans une commande arrête le bot si vous ne définissez pas bot.catch. Sans lui, grammY affiche No error handler was set!, arrête le polling et lève l’erreur, donc le processus se termine. Notre panneau relance un bot planté en 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.
• Un webhook resté sur le bot est supprimé pour vous. bot.start() appelle deleteWebhook avant de faire du polling et garde les messages en attente, sauf si vous passez drop_pending_updates: true. C’est important quand vous déplacez un bot depuis un hébergeur qui utilisait un webhook : Comment déplacer un bot Telegram vers PlayNHost.
• Une autre copie du bot arrête celui-ci. Sur 409 Conflict (le même token en polling ailleurs), bot.start() échoue au lieu de réessayer. Le panneau 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.
• Les erreurs réseau au démarrage sont réessayées discrètement. Si le premier appel à Telegram échoue à cause du réseau, grammY réessaie avec des attentes de plus en plus longues (jusqu’à 20 minutes entre deux essais dans la version 1.46.0) et n’affiche rien. Pour voir ces essais, sur la page Bot, volet Environnement, ajoutez la variable DEBUG avec la valeur grammy* (Ajouter la variable) et redémarrez.
• Version de Node.js : grammY 1.46.0 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 de mémoire : le script de démarrage fixe 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 grammY (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=grammY 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). 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, 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 fait tourner n’importe quoi, et vous pouvez lui donner un domaine avec HTTPS pour un webhook.

Sur une offre bot PlayNHost, le panneau s’en charge :

• 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 panneau.

Voir aussi Comment utiliser une base de données MySQL avec un bot grammY (mysql2).

Questions fréquentes

Est-ce la même chose que le bot de départ du panneau ?

C’est proche. Sur un serveur Node.js, Créer un bot de départ écrit index.js et package.json avec grammY ^1.46.0 : il répond à /start avec votre prénom, affiche Logged in as @your_bot, intercepte les erreurs avec bot.catch et affiche une ligne claire quand Telegram refuse le token. Modifiez-le comme vous voulez, puis redémarrez.

Dois-je supprimer mon webhook avant bot.start() ?

Non. bot.start() le supprime avec deleteWebhook avant de faire du polling, et les messages qui attendaient sont conservés. Si votre ancien code utilisait webhookCallback(bot, ...) avec un serveur web, remplacez-le par bot.start() : ces offres n’ont pas encore d’adresse HTTPS publique pour un webhook.

bot.start() suffit-il pour un bot très sollicité ?

Pour la plupart des bots, oui. bot.start() traite les messages l’un après l’autre ; les notes de grammY indiquent qu’il convient jusqu’à environ 5.000 messages par heure, et renvoient au paquet @grammyjs/runner pour davantage, ou pour les commandes longues, comme de gros transferts de fichiers. Le runner utilise aussi le long polling, donc il fonctionne sur nos offres.

Puis-je faire tourner grammY sur Bun ou Deno au lieu de Node.js ?

Oui. Lors de la commande, choisissez Bun ou Deno à la place de Node.js : notre page d’hébergement de bots Telegram liste grammY pour les deux. Les étapes de cette page concernent Node.js.

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