Héberger un bot pyTelegramBotAPI 24/7

Pour héberger un bot pyTelegramBotAPI (telebot) 24/7, faites-le tourner sur une machine qui reste allumée plutôt que sur votre PC : un VPS Linux avec un service systemd qui le relance après un plantage ou un redémarrage, ou une offre bot PlayNHost (à partir de 1,99 $US par mois, voir hébergement de bots Telegram), où vous envoyez votre code, collez le token et cliquez sur Démarrer. Lors de notre test, un bot pyTelegramBotAPI 4.37.1 a utilisé environ 40 Mo de mémoire au repos ; notre plus petite offre bot, STARTER, offre 0,5 Go. Les deux solutions utilisent le long polling : bot.infinity_polling() demande à Telegram les nouveaux messages, donc le bot n'a besoin d'aucune adresse publique. Les étapes sur PlayNHost :

1. Dans Telegram, envoyez /newbot à @BotFather et copiez le token qu'il vous donne.
2. Sur 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 Python.
3. Ouvrez votre serveur dans le panel. La carte Configurer votre bot sur Aperçu s'ouvre sur Connexion à Telegram ; sa première étape, Ce qui tourne, doit afficher Ce bot fait tourner Python Bot.
4. À l'étape Connexion à Telegram, collez le token et cliquez sur Connexion. Vérifiez le nom du bot affiché et cliquez sur Oui, continuer.
5. À l'étape Votre code, cliquez sur Téléverser des fichiers pour ouvrir Files et envoyez bot.py et requirements.txt, ou cliquez sur Connecter Git. Dans requirements.txt, le paquet est pyTelegramBotAPI, pas telebot.
6. Sur la page Bot, volet Code, vérifiez que Fichier d’entrée est le fichier qui appelle infinity_polling() (bot.py par défaut) et que Runtime est Python 3.11 ou plus récent.
7. Cliquez sur Démarrer le bot, ouvrez Console et attendez Logged in as @your_bot. La pastille sur Aperçu passe à En ligne sur Telegram. Envoyez /start à votre bot.

Le premier démarrage est plus long, le temps que pip installe pyTelegramBotAPI. Ensuite, il ne réinstalle que lorsque votre fichier de dépendances, les paquets supplémentaires ou la version de Python changent, ou une fois par jour. Pas à pas avec captures d'écran : Comment héberger un bot Telegram.

Ce que nous avons mesuré

Nous avons fait tourner les trois bibliothèques Python pour Telegram sur l'un de nos propres serveurs, dans des conteneurs jetables configurés comme le panel exécute un bot Python : Python 3.12 (le Runtime marqué recommandé), paquets installés avec la même commande pip, une limite de mémoire de 1 Go et un cœur de processeur.

Chaque bot a chargé la bibliothèque et demandé à Telegram qui il est avec un faux token (pyTelegramBotAPI : bot.get_me() sur le TeleBot simple). La mémoire correspond à ce que les processus du bot occupaient 15 secondes après le refus du token par Telegram ; le temps de démarrage court du lancement de Python jusqu'à ce que la bibliothèque signale cette réponse, il inclut donc un aller-retour vers Telegram. Les deux valeurs sont la médiane de trois exécutions après une exécution d'échauffement.

Ces chiffres sont le plancher de la bibliothèque : pas de conversations, aucun gestionnaire au travail, rien en cache. Votre propre code, les données qu'il garde en mémoire et le nombre de conversations qu'il gère s'y ajoutent, dimensionnez donc l'offre selon ce que fait votre bot. La taille installée inclut les deux bibliothèques HTTP dont dépend pyTelegramBotAPI, requests et aiohttp, même si vous n'utilisez que le TeleBot simple.

Un bot pyTelegramBotAPI minimal

Il répond à /start, lit le token que le panel lui donne et affiche une ligne de démarrage. Mettez la bibliothèque dans requirements.txt :

pyTelegramBotAPI>=4,<5

Et le code dans bot.py :

import os

import telebot

bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "Hello! I am running on PlayNHost.")


bot.delete_webhook()
print(f"Logged in as @{bot.user.username}")
bot.infinity_polling()

Les deux appels avant le polling comptent sur un hébergeur. delete_webhook() supprime un webhook laissé par un autre hébergeur, et bot.user demande à Telegram qui est le bot, de sorte que Logged in as @your_bot n'apparaît qu'avec un token que Telegram accepte. Le panel lit cette ligne pour afficher En ligne sur Telegram. Les deux appels arrêtent aussi le bot immédiatement avec une erreur claire quand le token est faux, au lieu de laisser le polling réessayer en arrière-plan. Le panel donne le token à votre code sous le nom TELEGRAM_BOT_TOKEN, et aussi sous BOT_TOKEN, TOKEN et TELEGRAM_TOKEN.

Si le token est faux

Lors de notre test, avec un token que Telegram refuse, notre bot de test a affiché :

ApiTelegramException: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized

Dans un traceback complet, la classe s'écrit telebot.apihelper.ApiTelegramException. Avec le bot ci-dessus, le premier appel échoue et le bot s'arrête avec le code de sortie 1 ; sur PlayNHost, le panel affiche Telegram n’a pas accepté le token de votre bot au-dessus de la console, avec Remplacer le token. Pour corriger, copiez à nouveau le token : dans @BotFather, envoyez /mybots, choisissez votre bot, puis API Token. Collez-le sur la page Bot, volet Telegram, sous Jeton, puis redémarrez le bot.

Un bot qui appelle infinity_polling() tout de suite, comme le font la plupart des exemples, se comporte autrement : il ne s'arrête pas. Le polling demande d'abord à Telegram qui est le bot ; avec un token refusé, cela échoue, et le bot journalise Infinity polling exception: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized puis réessaie toutes les 3 secondes, tant que le processus tourne. Un token révoqué alors que le bot fait déjà du polling donne à la place Threaded polling exception: avec le même message, réessayé après une attente qui double à chaque fois, jusqu'à une minute. Dans les deux cas, le bot a l'air de tourner alors que rien ne répond. Le panel reconnaît les deux lignes et affiche la même bannière.

Ce qu'un hébergeur doit savoir sur pyTelegramBotAPI

• Noms du paquet et de l'import : vous installez pyTelegramBotAPI et vous importez telebot. Le paquet PyPI nommé telebot est un autre petit projet ; mettez pyTelegramBotAPI dans requirements.txt.
• Version de Python : pyTelegramBotAPI 4.37.1 demande Python 3.11 ou plus récent. Sous Python 3.10, pip n'échoue pas : il installe la 4.37.0, la dernière version compatible avec 3.10. Gardez Runtime dans le volet Code sur 3.11 ou plus récent (3.12 est marqué recommandé) pour obtenir la version actuelle.
• infinity_polling() ou polling() : utilisez infinity_polling(). Le polling() simple s'arrête à la première erreur de Telegram, et une exception dans l'un de vos gestionnaires y met fin aussi, donc le bot quitte. Avec infinity_polling(), les erreurs de Telegram sont réessayées, et toute autre exception dans un gestionnaire est journalisée sous la forme Infinity polling exception: ... avant que le polling ne reparte 3 secondes plus tard.
• Journalisation : pyTelegramBotAPI a son propre logger, TeleBot, réglé sur ERROR, donc il n'affiche rien au démarrage ; c'est pourquoi le bot ci-dessus affiche sa propre ligne de démarrage. Les erreurs apparaissent sur une ligne sans traceback. Pour voir où un gestionnaire a échoué, démarrez avec bot.infinity_polling(logger_level=logging.DEBUG) (et import logging), ce qui ajoute le traceback. Ces lignes masquent la partie secrète de votre token.
• Un webhook laissé par un autre hébergeur : le polling ne le supprime pas, et Telegram refuse le polling tant qu'un webhook est défini. Gardez bot.delete_webhook() comme ci-dessus, ou cliquez sur Retirer le webhook sur la page Bot, volet Telegram.
• Threads ou asyncio : TeleBot utilise requests et exécute les gestionnaires dans deux threads de travail par défaut (num_threads=2) ; un gestionnaire lent en bloque un. AsyncTeleBot de telebot.async_telebot utilise aiohttp et se lance avec asyncio.run(bot.polling()). Les deux fonctionnent de la même façon sur le panel.
• Une seconde copie : quand une autre copie fait du polling avec le même token, Telegram répond 409 Conflict et infinity_polling() réessaie tant qu'il tourne. Le panel affiche Votre bot tourne aussi ailleurs. Voir Corriger l’erreur 409 Conflict d’un bot Telegram.

Héberger soi-même sur un VPS Linux

Sous Debian ou Ubuntu, installez Python, créez un utilisateur pour le bot et installez la bibliothèque dans un environnement virtuel. Vérifiez d'abord python3 --version : en dessous de 3.11, pip installe un pyTelegramBotAPI plus ancien.

sudo apt update
sudo apt install -y python3 python3-venv
sudo useradd --system --create-home --home-dir /opt/tgbot --shell /usr/sbin/nologin tgbot
sudo cp bot.py requirements.txt /opt/tgbot/
sudo -u tgbot python3 -m venv /opt/tgbot/venv
sudo -u tgbot /opt/tgbot/venv/bin/pip install -r /opt/tgbot/requirements.txt

Mettez le token dans un fichier que seul root peut lire. Ouvrez-le avec sudo nano /etc/tgbot.env, écrivez une ligne, enregistrez, puis lancez sudo chmod 600 /etc/tgbot.env :

TELEGRAM_BOT_TOKEN=123456789:your-token-from-botfather

Créez /etc/systemd/system/tgbot.service :

[Unit]
Description=Telegram bot (pyTelegramBotAPI)
Wants=network-online.target
After=network-online.target

[Service]
User=tgbot
WorkingDirectory=/opt/tgbot
EnvironmentFile=/etc/tgbot.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/opt/tgbot/venv/bin/python /opt/tgbot/bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Démarrez-le maintenant et à chaque démarrage du système, puis suivez sa sortie :

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

PYTHONUNBUFFERED=1 compte ici : quand la sortie de Python ne va pas vers un terminal, elle est mise en mémoire tampon par blocs, donc sans cette variable Logged in as peut rester dans un tampon au lieu d'atteindre le journal. Restart=always relance aussi le bot 5 secondes après son arrêt sur un token faux, vérifiez donc le journal s'il redémarre sans cesse. Après avoir modifié le code, lancez sudo systemctl restart tgbot. Arrêtez d'abord toute copie sur votre PC, sinon Telegram répond 409 Conflict.

Auto-hébergement ou offre bot

• Sur un VPS que vous gérez : les mises à jour du système, la version de Python, l'environnement virtuel, la réinstallation des paquets, le fichier d'unité, la lecture du journal et le fait de remarquer quand le bot ne répond plus. En échange, vous avez root et vous pouvez utiliser un webhook si vous ajoutez un domaine et HTTPS.
• Sur une offre bot, le panel s'en charge : il installe requirements.txt quand il change, relance le bot après un plantage, vérifie le token auprès de Telegram avant de l'enregistrer, le donne à votre code sous cinq noms, lit la console et nomme la cause quand le bot ne répond plus (un token refusé, une seconde copie, un webhook), avec un bouton pour le token et le webhook. Nos offres bot n'incluent pas encore d'adresse HTTPS publique, donc les bots y utilisent le long polling, ce que fait infinity_polling().

Questions fréquentes

Pourquoi mon bot telebot tourne-t-il mais ne répond-il jamais ?

Parce que infinity_polling() réessaie chaque erreur de Telegram sans s'arrêter : un token refusé, une autre copie qui utilise le même token, un webhook resté sur le bot. Cherchez les lignes contenant Infinity polling exception (un token refusé au démarrage) ou Threaded polling exception (une fois le polling lancé) dans la Console ; le panel transforme chacune des trois causes en une bannière qui la nomme.

J'obtiens ModuleNotFoundError: No module named 'telebot'. Que manque-t-il ?

Le paquet. Ajoutez pyTelegramBotAPI à requirements.txt et redémarrez le bot : le fichier de dépendances a changé, donc pip l'installe à ce démarrage. L'import reste import telebot.

pyTelegramBotAPI a-t-il besoin d'un webhook pour rester en ligne ?

Non. infinity_polling() continue de demander à Telegram les nouveaux messages, donc le bot répond tant que le processus tourne. Pour déplacer un bot qui utilisait un webhook : Comment déplacer un bot Telegram vers PlayNHost.

Faut-il utiliser TeleBot ou AsyncTeleBot ?

Les deux fonctionnent sur une offre bot. Utilisez celui que votre code ou votre tutoriel utilise : avec TeleBot, les gestionnaires sont de simples fonctions ; avec AsyncTeleBot, ce sont des fonctions async def qui font await sur les méthodes du bot. Notre mesure ci-dessus concerne le TeleBot simple.

pyTelegramBotAPI fonctionne sur toutes les offres bot PlayNHost, à partir de STARTER (0,5 Go). Comparez les offres et cliquez sur Créer un serveur sur hébergement de bots Telegram.