Comment héberger un bot aiogram 24/7 : forfait bot ou VPS Linux

Pour héberger un bot aiogram 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 un forfait 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 aiogram 3.31.0 a utilisé environ 173 Mo de mémoire au repos ; notre plus petit forfait bot, STARTER, offre 0,5 Go. Les deux solutions utilisent le long polling : dp.start_polling(bot) 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 un forfait. 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 indiquer Ce bot fait tourner Python Bot.
4. Sous Connexion à Telegram, collez le token et cliquez sur Connexion. Vérifiez le nom du bot affiché et cliquez sur Oui, continuer.
5. Sous Votre code, cliquez sur Téléverser des fichiers pour ouvrir Files et envoyez bot.py et requirements.txt, ou cliquez sur Connecter Git.
6. Sur la page Bot, volet Code, vérifiez que le Fichier d’entrée est le fichier qui exécute asyncio.run(main()) (bot.py par défaut).
7. Cliquez sur Démarrer le bot, ouvrez la Console et attendez la ligne d’aiogram Run polling for bot @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 aiogram et ses dépendances. Ensuite, il ne réinstalle que lorsque votre fichier requirements, 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é comme recommandé), paquets installés avec la même commande pip, une limite de mémoire de 1 Go et un cœur de CPU.

Chaque bot a chargé la bibliothèque et demandé à Telegram qui il est avec un faux token (aiogram : bot.get_me()). 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 de préchauffage.

Ces chiffres sont le plancher de la bibliothèque : aucune discussion, aucun handler au travail, rien en cache. Votre propre code, les données qu’il garde en mémoire (par exemple les états de conversation dans le stockage mémoire d’aiogram) et le nombre de discussions qu’il gère s’y ajoutent, dimensionnez donc le forfait selon ce que fait votre bot. Notre ancienne page python-telegram-bot vs aiogram sur PlayNHost a mesuré une configuration différente (Python 3.13, un bot construit et prêt à démarrer), ses chiffres ne sont donc pas comparables à ceux-ci.

Un bot aiogram minimal

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

aiogram>=3,<4

Et le code dans bot.py :

import asyncio
import logging
import os
import sys

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

dp = Dispatcher()


@dp.message(CommandStart())
async def start(message: Message) -> None:
    await message.answer("Hello! I am running on PlayNHost.")


async def main() -> None:
    bot = Bot(os.environ["BOT_TOKEN"])
    async with bot.context():
        await bot.delete_webhook()
        await dp.start_polling(bot)


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

Il lit BOT_TOKEN, le nom qu’utilisent les propres exemples d’aiogram ; le panel donne le token à votre code sous ce nom ainsi que sous TELEGRAM_BOT_TOKEN, TOKEN et TELEGRAM_TOKEN. La journalisation au niveau INFO fait qu’aiogram affiche une ligne qui commence par INFO:aiogram.dispatcher:Run polling for bot @your_bot dès que Telegram a accepté le token, et le panel lit cette ligne pour afficher En ligne sur Telegram, vous n’avez donc pas besoin de print. delete_webhook() supprime un webhook laissé par un autre hébergeur avant le début du polling. async with bot.context() ferme la connexion du bot à Telegram quand main() se termine, y compris sur une erreur.

Si le token est incorrect

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

TelegramUnauthorizedError: Telegram server says - Unauthorized

Dans une trace complète, la classe s’écrit aiogram.exceptions.TelegramUnauthorizedError. Le premier appel à Telegram échoue (dans le bot ci-dessus, delete_webhook() ; sans lui, le getMe que fait start_polling), si bien que le bot s’arrête aussitôt 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, et redémarrez le bot.

Deux autres cas se présentent autrement. Un token contenant une espace, ou sans le numéro du bot et les deux-points devant le secret, échoue avant toute requête : Bot() vérifie la forme et lève TokenValidationError avec un message qui commence par Token is invalid!. Un token révoqué alors que le bot fait déjà du polling ne l’arrête pas : aiogram journalise Failed to fetch updates - TelegramUnauthorizedError et réessaie toutes les quelques secondes, le processus semble donc tourner alors que rien ne répond. La bannière du panel vous permet de le remarquer.

Ce qu’un hébergeur doit savoir sur aiogram

• Noms du paquet et de l’import : les deux sont aiogram. Il installe avec lui aiohttp, pydantic, magic-filter, aiofiles et certifi.
• Version de Python : aiogram 3.31 nécessite Python 3.10 à 3.14. Le Runtime du volet Code propose exactement 3.10 à 3.14, avec 3.12 marqué comme recommandé.
• Le code aiogram 2 ne fonctionne pas sur aiogram 3 : l’Executor a été supprimé, donc executor.start_polling(dp) devient await dp.start_polling(bot). Un tutoriel dont le requirements.txt fixe une version 2.x, comme aiogram==2.25.2, est du code de la version 2 ; voir la question plus bas.
• Un webhook laissé par un autre hébergeur : start_polling ne le supprime pas, et Telegram refuse le polling tant qu’un webhook est défini, donc aiogram journalise TelegramConflictError et réessaie. Gardez await bot.delete_webhook() comme ci-dessus, ou cliquez sur Retirer le webhook sur la page Bot, volet Telegram.
• Journalisation : sans logging.basicConfig, les lignes INFO d’aiogram, dont la ligne de disponibilité, ne s’affichent pas. Au niveau INFO, il journalise aussi une ligne par update (Update id=... is handled) ; sur un bot très sollicité, ajoutez logging.getLogger("aiogram.event").setLevel(logging.WARNING), qui conserve la ligne de disponibilité.
• Quels updates arrivent : si vous ne passez pas allowed_updates, start_polling ne demande à Telegram que les types d’update pour lesquels vous avez des handlers.
• Une seconde copie : quand une autre copie fait du polling avec le même token, Telegram répond 409 Conflict et aiogram réessaie tant qu’il tourne. 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

Sur Debian ou Ubuntu, installez Python, créez un utilisateur pour le bot et installez aiogram dans un environnement virtuel. Vérifiez que python3 --version indique 3.10 à 3.14.

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 exécutez sudo chmod 600 /etc/tgbot.env :

BOT_TOKEN=123456789:your-token-from-botfather

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

[Unit]
Description=Telegram bot (aiogram)
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, puis suivez sa sortie :

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

Les lignes de journalisation arrivent dans le journal au fur et à mesure ; PYTHONUNBUFFERED=1 fait de même pour tout print() que vous ajoutez, que Python garde sinon dans un tampon quand il n’écrit pas dans un terminal. systemctl stop tgbot envoie SIGTERM, que start_polling gère en arrêtant le polling et en fermant la session du bot. Après avoir modifié le code, exécutez sudo systemctl restart tgbot. Arrêtez d’abord toute copie sur votre PC, sinon Telegram répond 409 Conflict.

Auto-hébergement ou forfait 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 cesse de répondre. En échange, vous avez root et vous pouvez utiliser le mode webhook d’aiogram si vous ajoutez un domaine et HTTPS.
• Sur un forfait 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 cesse de répondre (un token refusé, une seconde copie, un webhook), avec un bouton pour le token et le webhook. Nos forfaits bot n’incluent pas encore d’adresse HTTPS publique, les bots y utilisent donc le long polling, ce que fait start_polling.

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

Questions fréquentes

Puis-je faire tourner un bot aiogram 2 ?

Portez-le vers aiogram 3 si vous le pouvez : le guide de migration d’aiogram liste les changements, à commencer par l’Executor supprimé. La dernière version d’aiogram 2, la 2.25.2, est sortie le 6 octobre 2023. Elle indique Python 3.7 à 3.10 comme pris en charge et nécessite aiohttp antérieur à 3.9, que PyPI propose en paquets précompilés seulement jusqu’à Python 3.11. Si vous devez faire tourner l’ancien code avant de le porter, fixez aiogram==2.25.2 dans requirements.txt et réglez le Runtime sur Python 3.10, la version la plus récente qu’elle indique.

Pourquoi mon bot aiogram semble-t-il tourner mais ne répond jamais ?

aiogram continue de réessayer une fois le polling démarré : avec un token révoqué dans @BotFather, avec une autre copie qui utilise le même token et avec un webhook resté sur le bot. Lisez les lignes qui commencent par Failed to fetch updates dans la Console ; le panel transforme chacun de ces trois cas en une bannière qui nomme la cause, avec un bouton pour le token et le webhook.

Où vivent les états FSM d’aiogram ?

Avec le stockage mémoire par défaut, dans le processus du bot : ils sont perdus au redémarrage du bot, par exemple après une modification du code. Pour les conserver, utilisez un stockage hors du processus, comme le stockage Redis d’aiogram avec un serveur Redis que vous pouvez joindre.

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

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

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