Comment configurer un bot Matrix avec Python et la bibliothèque Simple-Matrix-Bot-Lib

Que choisissez-vous réellement lorsque vous construisez un bot Matrix de cette manière ?

Simple-Matrix-Bot-Lib est une surcouche logicielle pour la matrix-niobibliothèque cliente Python. Elle s'avère donc intéressante pour créer un petit bot de commandes, de notifications ou d'assistance pour les salons de discussion, sans avoir à implémenter soi-même l'intégralité de la boucle de synchronisation et de gestion des événements Matrix. En contrepartie, vous acceptez les abstractions et les modèles d'authentification proposés par cette surcouche, au lieu de contrôler directement chaque détail du client Matrix.

Au 6 octobre 2026, PyPI répertorie la simplematrixbotlibversion 2.13.1, publiée le 29 mars 2026, qui requiert Python 3.9 ou une version plus récente, mais antérieure à Python 4. Le site Read the Docs du projet avertit actuellement que sa documentation n'est plus maintenue et peut être obsolète ; par conséquent, ce guide utilise PyPI et la spécification Matrix actuelle comme références principales et considère la documentation plus ancienne comme un guide d'implémentation plutôt que comme une preuve du comportement actuel.

Pour le package lui-même, consultez le projet simplematrixbotlib sur PyPI . Pour le comportement du protocole, utilisez la spécification actuelle de l'API client-serveur Matrix .

Simple-Matrix-Bot-Lib, matrix-nio ou un service d'application ?

Si votre objectif est de « répondre aux commandes dans les salons avec un seul compte bot », Simple-Matrix-Bot-Lib est généralement la solution la plus rapide. Si vous savez déjà que vous avez besoin d'une authentification personnalisée, d'un comportement de synchronisation particulier, d'une vérification détaillée des appareils ou d'un contrôle du chiffrement de bas niveau, utiliser matrix-nio dès le départ vous évitera de devoir créer un wrapper ultérieurement. Pour les ponts ou les intégrations nécessitant un routage au niveau du serveur d'accueil, consultez l' API Matrix Application Service plutôt que d'utiliser un compte bot classique.

Étape 1 : Choisissez un serveur d’hébergement et confirmez comment le bot peut s’y connecter.

Un bot Matrix nécessite un compte utilisateur Matrix sur un serveur d'accueil. Vous pouvez utiliser un serveur d'accueil public autorisant la création de comptes ou un compte sur un serveur d'accueil que vous administrez. Veillez à bien dissocier le bot de votre identité Matrix personnelle afin de gérer indépendamment les permissions, l'appartenance aux salons et les identifiants.

Le choix crucial concerne l'authentification. La spécification Matrix actuelle prend en charge l'API d'authentification traditionnelle et OAuth 2.0. Un serveur d'accueil peut exposer l'une ou l'autre, voire les deux. Les exemples de démarrage rapide publiés par Simple-Matrix-Bot-Lib utilisent une URL, un nom d'utilisateur et un mot de passe de serveur d'accueil ; ce tutoriel suppose donc que votre serveur propose toujours une procédure d'authentification par mot de passe compatible.

Avant d'écrire du code, vérifiez les méthodes de connexion exposées par votre serveur domestique :

curl https://matrix.example.com/_matrix/client/v3/login

Si la réponse inclut un flux de connexion par mot de passe, l'exemple ci-dessous, basé sur les identifiants, convient parfaitement. Si le serveur n'accepte que l'authentification unique (SSO) ou OAuth, n'imposez pas de mot de passe dans l'exemple. Dans ce cas, vérifiez la prise en charge de l'authentification dans la version actuelle de la bibliothèque ou utilisez un client de bas niveau compatible avec le flux souhaité. La spécification Matrix explique la découverte des identifiants et la gestion des jetons dans la section « Connexion » de l'API Client-Serveur .

Étape 2 : Créez un environnement Python isolé et installez la bibliothèque

Utilisez un environnement virtuel afin de séparer les dépendances du bot de Python système et des projets sans lien avec celui-ci. Les métadonnées PyPI actuelles requièrent Python 3.9 ou une version ultérieure.

mkdir matrix-bot
cd matrix-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install simplematrixbotlib

Sous Windows PowerShell, activez l'environnement avec :

.venv\Scripts\Activate.ps1

Vérifiez ce qui a été installé plutôt que de supposer une version à partir d'un ancien tutoriel :

python -m pip show simplematrixbotlib

Cette vérification de version est importante car les pages Read the Docs publiques affichent encore d'anciennes documentations et signalent explicitement qu'elles peuvent être obsolètes. Si un exemple de ces pages entre en conflit avec le paquet installé, examinez les métadonnées de la version et le dépôt actuel avant de modifier votre code pour qu'il corresponde à l'ancienne page.

Avez-vous besoin d'un chiffrement de bout en bout ?

Tous les bots ne fonctionnent pas ainsi. Un bot qui se contente de rejoindre des salons opérationnels non chiffrés est plus simple à déployer et n'a pas besoin de gérer l'état du chiffrement. Un bot censé lire et répondre dans des salons chiffrés nécessite des dépendances supplémentaires et un état de chiffrement persistant.

La documentation de Simple-Matrix-Bot-Lib et celle de matrix-nio indiquent toutes deux que le chiffrement de bout en bout (E2EE) repose sur le support de chiffrement de matrix-nio et libolm-devsur libolm. Sous Debian ou Ubuntu, la documentation de matrix-nio explique comment installer le module complémentaire E2EE :

sudo apt-get install libolm-dev
python -m pip install "matrix-nio[e2e]"

N'activez pas le chiffrement de bout en bout (E2EE) simplement parce que Matrix le prend en charge. Utilisez-le uniquement lorsque les salles nécessitent un chiffrement et que vous êtes prêt à stocker localement les données du bot et à gérer la confiance des appareils. La documentation de matrix-nio indique que l'état du chiffrement, les clés et la confiance des appareils sont stockés localement lorsque le chiffrement de bout en bout est activé.

Étape 3 : Créez le compte du bot et veillez à ne pas inclure les identifiants dans le code source.

Créez un compte Matrix dédié via un client ou le processus de gestion de compte fourni par votre serveur. L'interface d'inscription exacte varie selon le fournisseur ; ce guide ne présuppose donc pas l'utilisation d'un écran Element particulier ni ne garantit que l'inscription libre est disponible partout.

Pour le développement, exportez trois variables d'environnement :

export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_USERNAME="botname"
export MATRIX_PASSWORD="replace-with-a-secret"

Les variables d'environnement sont pratiques pour un tutoriel local, mais ne constituent pas automatiquement un système de gestion des secrets adapté à la production. Sur un VPS ou une plateforme de conteneurs, privilégiez le gestionnaire de secrets de la plateforme, un fichier d'environnement protégé hors du système de contrôle de version, ou un gestionnaire de secrets dédié. Ne jamais enregistrer un mot de passe Matrix ou un jeton d'accès dans Git.

Invitez le compte du bot dans une salle de test et acceptez l'invitation avec un client Matrix si votre serveur ou la configuration de votre bot ne permet pas l'adhésion automatique aux invitations. Commencez par une salle de test privée. Cela limite l'exécution accidentelle de commandes pendant que vous validez le comportement du bot.

Étape 4 : Écrire, exécuter et tester un bot de commandes minimal

Créez-le bot.pyavec une petite !pingcommande. La structure ci-dessous suit l'exemple du package public : créez Creds, créez Bot, ajoutez un écouteur de messages asynchrone, utilisez MessageMatch, et envoyez un message texte via bot.api.

import os
import simplematrixbotlib as botlib

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USERNAME = os.environ["MATRIX_USERNAME"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
PREFIX = "!"

creds = botlib.Creds(HOMESERVER, USERNAME, PASSWORD)
bot = botlib.Bot(creds)

@bot.listener.on_message_event
async def ping(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if (
        match.is_not_from_this_bot()
        and match.prefix()
        and match.command("ping")
    ):
        await bot.api.send_text_message(room.room_id, "Pong!")

bot.run()

Exécutez-le depuis l'environnement virtuel activé :

python bot.py

Dans la salle de test, envoyez :

!ping

Un résultat positif est simple : le bot reste connecté, détecte l’événement de la salle et répond Pong!. Vérifiez également qu’il ne répond pas à sa propre réponse. Cette is_not_from_this_bot()vérification est importante car un bot de type « écho » mal conçu peut sinon créer des boucles de rétroaction.

Quand faut-il ajouter une liste blanche ?

Ajoutez une restriction avant que le bot ne déclenche des actions sensibles. Une commande qui se contente de renvoyer « Pong ! » a peu d'impact, mais une commande qui lance des déploiements, interroge les systèmes internes ou publie des données confidentielles ne doit pas être exécutée pour chaque utilisateur dans chaque salon.

Simple-Matrix-Bot-Lib présente la gestion des accès utilisateurs et la configuration des listes d'autorisation/de blocage comme des fonctionnalités. Pour un bot en production, l'autorisation doit être considérée comme une logique applicative et non comme une simple étape de finition. Limitez l'accès par identifiant utilisateur, identifiant de salle ou les deux, et conservez des permissions côté serveur sur les systèmes en aval comme deuxième ligne de défense.

Connexion par mot de passe versus jetons d'accès : quel est le compromis pratique ?

La connexion par mot de passe est simple et conforme à l'exemple minimal fourni avec le package. En revanche, un bot fonctionnant en continu doit posséder le mot de passe du compte, alors que certaines configurations Matrix modernes privilégient l'authentification unique (SSO) ou les flux OAuth.

Les jetons d'accès réduisent la réutilisation des mots de passe, mais leur cycle de vie dépend du système d'authentification. La spécification Matrix indique que les jetons d'accès doivent être traités comme des identifiants opaques et transmis via le Authorization: Bearerprotocole HTTP. Les versions actuelles de Matrix prennent également en charge l'expiration des jetons d'accès et l'actualisation des jetons dans certains flux. Un exemple conçu pour les identifiants par mot de passe ne gère pas automatiquement l'actualisation, la révocation ou l'authentification OAuth.

Si la gestion du cycle de vie des jetons, l'authentification unique (SSO), OAuth ou l'authentification par compte de service sont essentielles à votre déploiement, vérifiez que cette fonctionnalité est bien présente dans la version exacte de Simple-Matrix-Bot-Lib que vous installez. Si l'interface ne permet pas un contrôle suffisant, l'utilisation directe de matrix-nio est une solution plus propre.

Faut-il exécuter le bot sur un ordinateur portable, un VPS, un conteneur ou Kubernetes ?

Pour un bot léger non chiffré, une petite machine virtuelle ou un conteneur suffit généralement. Pour un bot chiffré, la persistance des données devient une exigence de conception : la perte du stockage de données chiffrées local peut modifier l’identité de l’appareil et compromettre la confiance. Les exemples E2EE de matrix-nio insistent sur la préservation de l’identifiant de l’appareil et du stockage de données chiffrées lors des redémarrages.

Erreurs de configuration courantes et leur signification habituelle

• La connexion échoue immédiatement : vérifiez l’URL du serveur et inspectez-la /_matrix/client/v3/login. Un serveur qui n’affiche pas de mot de passe de connexion peut ne pas fonctionner avec un démarrage rapide basé sur un mot de passe.
• Le bot démarre mais ne reçoit jamais de messages : vérifiez que le compte du bot est bien connecté à la salle et que vous effectuez un test avec un événement texte normal.
• Le bot répond de manière répétée : assurez-vous que le gestionnaire ignore les événements envoyés par le bot lui-même.
• Les salles chiffrées sont illisibles : l’installation du paquet de base ne suffit pas. Ajoutez les dépendances matrix-nio E2EE, activez le chiffrement conformément à la configuration de la bibliothèque et conservez le stockage cryptographique.
• Un ancien exemple génère une erreur d'API : vérifiez la version du paquet installé. La documentation publique de Simple-Matrix-Bot-Lib indique qu'elle n'est plus maintenue ; les exemples peuvent donc être en retard par rapport à la version publiée sur PyPI.

Quel chemin choisir ?

Choisissez Simple-Matrix-Bot-Lib si votre bot ne gère qu'un seul utilisateur Matrix, que vos commandes sont simples et que vous privilégiez un code Python concis plutôt qu'un contrôle précis du protocole. Cette bibliothèque est particulièrement adaptée aux prototypes, aux bots de notification, aux utilitaires de salle de discussion et aux petites automatisations internes.

Choisissez directement matrix-nio lorsque le chiffrement, la vérification des appareils, l'authentification personnalisée, les types d'événements, le comportement de synchronisation ou la gestion des jetons sont des exigences essentielles. Vous écrirez plus de code, mais le niveau d'abstraction sera plus bas et plus facile à appréhender pour les tâches avancées liées à Matrix.

Choisissez un service d'application lorsque votre intégration constitue une extension, un pont ou une passerelle pour votre serveur d'accueil, et non un simple bot utilisateur. L'API du service d'application est conçue pour ce modèle de connexion serveur et nécessite la configuration du serveur d'accueil.

Pour un premier bot Matrix, l' !pingexemple minimal constitue un bon point de départ : s'il peut s'authentifier, rejoindre la bonne salle, ignorer ses propres événements et répondre de manière fiable, vous avez validé les bases. N'ajoutez le chiffrement, l'autorisation, les API externes et l'automatisation du déploiement qu'une fois ces fondations stables.

Références primaires

• Simple-Matrix-Bot-Lib sur PyPI — métadonnées actuelles du package, exigences Python, historique des versions et exemple de base.
• Documentation de Simple-Matrix-Bot-Lib — référence historique utile ; le site avertit actuellement qu’elle peut être obsolète.
• Documentation matrix-nio — bibliothèque cliente sous-jacente, dépendances E2EE, stockage et exemples.
• API client-serveur Matrix — comportement actuel du protocole d'authentification, de connexion, de jeton, de salle et d'événement.
• API Matrix Application Service — alternative intégrée au serveur pour les ponts et les intégrations plus importantes.