Héberger un bot python-telegram-bot 24/7

Pour héberger un bot python-telegram-bot 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 Start. Lors de notre test, un bot python-telegram-bot 22.8 a utilisé environ 44 Mo de mémoire au repos ; notre plus petite offre bot, STARTER, offre 0,5 Go. Les deux voies utilisent le long polling : run_polling() demande à Telegram les nouveaux messages, le bot n’a donc 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 ? avec Telegram et choisissez Python.
3. 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 Python Bot.
4. Dans Connexion à Telegram, collez le token et cliquez sur Connexion. Vérifiez le nom du bot affiché et cliquez sur Oui, continuer.
5. Dans Votre code, cliquez sur Téléverser des fichiers pour ouvrir Files et téléversez bot.py et requirements.txt, ou cliquez sur Connecter Git. Pas encore de code ? Créer un bot de départ écrit pour vous un bot python-telegram-bot 22.
6. Sur la page Bot, volet Code, vérifiez que Fichier d’entrée est le fichier qui appelle run_polling() (bot.py par défaut).
7. Cliquez sur Démarrer le bot, ouvrez Console et attendez Logged in as @your_bot. Le badge de Aperçu passe à En ligne sur Telegram. Envoyez /start à votre bot.

Le premier démarrage est plus long, le temps que pip installe python-telegram-bot. 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 lancé les trois bibliothèques Telegram pour Python 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é comme 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 (python-telegram-bot : Application.initialize()). 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 au moment où 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 de chauffe.

Ces chiffres sont le plancher de la bibliothèque : aucun chat, aucun handler à l’œuvre, rien en cache. Votre propre code, les données qu’il garde en mémoire et le nombre de chats qu’il gère s’y ajoutent, dimensionnez donc l’offre selon ce que fait votre bot. Notre ancienne page python-telegram-bot vs aiogram sur PlayNHost a mesuré une autre configuration (Python 3.13, un bot construit et prêt à démarrer), ses chiffres ne sont donc pas comparables à ceux-ci.

Un bot python-telegram-bot minimal

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

python-telegram-bot>=22,<23

Et le code dans bot.py :

import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.effective_message.reply_text("Hello! I am running on PlayNHost.")


async def post_init(application: Application) -> None:
    print(f"Logged in as @{application.bot.username}")


def main() -> None:
    application = (
        Application.builder()
        .token(os.environ["TELEGRAM_BOT_TOKEN"])
        .post_init(post_init)
        .build()
    )
    application.add_handler(CommandHandler("start", start))
    application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

post_init s’exécute une fois l’application initialisée, c’est le moment où python-telegram-bot vérifie le token auprès de Telegram, donc Logged in as @your_bot n’apparaît qu’une fois le token accepté par Telegram. Le panel lit cette ligne pour afficher En ligne sur Telegram. Le panel transmet le token à votre code sous le nom TELEGRAM_BOT_TOKEN, et aussi sous BOT_TOKEN, TOKEN et TELEGRAM_TOKEN, si bien que os.environ["TOKEN"] fonctionne aussi si vous partez des exemples de la bibliothèque, qui utilisent un espace réservé "TOKEN".

Si le token est incorrect

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

InvalidToken: The token `1000000000:AAFakeTokenForAMemoryTestNotReal00000` was rejected by the server.

python-telegram-bot vérifie le token avant le début du polling, le bot ci-dessus s’arrête donc aussitôt avec le code de sortie 1. La console affiche d’abord Network Retry Loop (Bootstrap Initialize Application): Invalid token. Aborting retry loop. avec une trace, puis la trace de l’erreur elle-même, dont la dernière ligne indique telegram.error.InvalidToken: The token `...` was rejected by the server. Sur PlayNHost, le panel affiche Telegram n’a pas accepté le token de votre bot au-dessus de la console, avec Remplacer le token. Notez que les deux traces contiennent le token lui-même : ne collez cette sortie de console nulle part en public.

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. Si le token est révoqué alors que le bot fait déjà du polling, python-telegram-bot journalise Network Retry Loop (Polling Updates): Invalid token. Aborting retry loop. et arrête le polling, mais le processus continue de tourner : le bot a l’air de fonctionner alors que rien ne répond. Le panel affiche la même bannière.

Ce qu’un hébergeur doit savoir sur python-telegram-bot

• Noms du paquet et de l’import : vous installez python-telegram-bot et vous importez telegram et telegram.ext.
• Version de Python : python-telegram-bot 22.8 exige Python 3.10 ou plus récent. Le Runtime du volet Code propose de 3.10 à 3.14, avec 3.12 marqué comme recommandé, tous les choix conviennent donc.
• Un webhook laissé par un autre hébergeur : avant de commencer le polling, run_polling() supprime tout webhook défini sur le bot, si bien qu’un bot venant d’un hébergeur à webhook fonctionne sans code supplémentaire. Les messages en attente chez Telegram sont conservés, sauf si vous passez drop_pending_updates=True.
• Journalisation : python-telegram-bot journalise son démarrage au niveau INFO, que Python n’affiche pas tant que vous n’avez pas configuré la journalisation, c’est pourquoi le bot ci-dessus affiche sa propre ligne de disponibilité. Avec logging.basicConfig(level=logging.INFO), il journalise INFO:telegram.ext.Application:Application started, que le panel lit aussi comme « prêt ». Si vous le faites, ajoutez aussi logging.getLogger("httpx").setLevel(logging.WARNING), comme le font les exemples de la bibliothèque : au niveau INFO, la bibliothèque HTTP journalise chaque URL de requête, et les URL de requête de Telegram contiennent votre token.
• Tâches planifiées : la JobQueue a besoin d’un extra. Écrivez python-telegram-bot[job-queue]>=22,<23 dans requirements.txt ; sans lui, application.job_queue vaut None et la bibliothèque avertit No `JobQueue` set up.
• Une deuxième copie : quand une autre copie fait du polling avec le même token, Telegram répond 409 Conflict. python-telegram-bot journalise Exception happened while polling for updates. et continue de réessayer, le bot a donc l’air de fonctionner mais manque des messages. Le panel affiche Votre bot tourne aussi ailleurs. Voir Corriger l’erreur 409 Conflict d’un bot Telegram.

L’héberger vous-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 que python3 --version indique 3.10 ou plus récent.

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 (python-telegram-bot)
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 boot, puis suivez sa sortie :

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

PYTHONUNBUFFERED=1 est important ici : quand la sortie de Python ne va pas vers un terminal, elle est mise en tampon par blocs, si bien que sans lui Logged in as peut rester dans un tampon au lieu d’atteindre le journal. systemctl stop tgbot envoie SIGTERM, que run_polling() gère en s’arrêtant proprement. 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 pouvez faire tourner un webhook si vous ajoutez un domaine et du 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 transmet à votre code sous cinq noms, lit la console et nomme la cause quand le bot ne répond plus (un token refusé, une deuxième copie, un webhook), avec un bouton pour le token et le webhook. Nos offres bot n’incluent pas encore d’adresse HTTPS publique, les bots y utilisent donc le long polling, ce que fait run_polling().

Voir aussi Comment utiliser une base de données MySQL avec un bot python-telegram-bot (aiomysql).

Questions fréquentes

Ai-je besoin d’un webhook pour garder un bot python-telegram-bot en ligne ?

Non. run_polling() garde une connexion ouverte avec Telegram et demande les nouveaux messages, le bot répond donc tant que le processus tourne. Un webhook demande une adresse HTTPS publique, que nos offres bot n’incluent pas encore. Pour déplacer un bot qui en utilisait un : Comment déplacer un bot Telegram vers PlayNHost.

Pourquoi mon token est-il apparu dans la console ?

Il apparaît à deux endroits courants : le message InvalidToken quand Telegram refuse le token, et les lignes de requête de la bibliothèque HTTP quand la journalisation est au niveau INFO. Réglez le logger httpx sur WARNING comme indiqué plus haut. Notre bot de départ intercepte aussi InvalidToken et affiche à la place une ligne simple.

Puis-je utiliser run_repeating et d’autres tâches planifiées ?

Oui, avec l’extra job-queue dans requirements.txt. L’extra installe APScheduler au prochain démarrage, car le fichier de dépendances a changé. Les tâches s’exécutent dans le processus du bot, elles continuent donc tant que le bot tourne.

Le bot de départ utilise-t-il python-telegram-bot ?

Oui. Sur un serveur Python, Créer un bot de départ écrit bot.py et un requirements.txt avec python-telegram-bot 22. Il répond à /start, affiche Logged in as @your_bot et garde le token hors de ses lignes de journal. Modifiez-le à votre guise, puis redémarrez.

python-telegram-bot 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.