Hoe stel je een Matrix-bot in met Python en Simple-Matrix-Bot-Lib?

Wat kies je eigenlijk als je op deze manier een Matrix-bot bouwt?

Simple-Matrix-Bot-Lib is een handige extra laag bovenop de Python- matrix-nioclientbibliotheek. Dit maakt het aantrekkelijk wanneer je een kleine commandobot, notificatiebot of room helper wilt zonder zelf de volledige Matrix-synchronisatie- en gebeurtenisafhandelingslus te hoeven schrijven. Het nadeel is dat je de abstracties en authenticatiepatronen accepteert die door de wrapper worden aangeboden, in plaats van elk detail van de Matrix-client rechtstreeks te beheren.

Op 6 oktober 2026 vermeldde PyPI versie simplematrixbotlib2.13.1, uitgebracht op 29 maart 2026, die Python 3.9 of nieuwer vereist, maar ouder dan Python 4. De Read the Docs-website van het project waarschuwt momenteel dat de documentatie niet wordt bijgehouden en mogelijk verouderd is. Daarom gebruikt deze handleiding PyPI en de huidige Matrix-specificatie als primaire referenties en beschouwt oudere documentatie als implementatierichtlijnen in plaats van als bewijs van het huidige gedrag.

Voor het pakket zelf, zie het simplematrixbotlib-project op PyPI . Voor het protocolgedrag, gebruik de huidige Matrix Client-Server API-specificatie .

Simple-Matrix-Bot-Lib, matrix-nio of een applicatieservice?

Als je doel is om "commando's in chatrooms te beantwoorden als één botaccount", is Simple-Matrix-Bot-Lib meestal de kortste weg. Als je al weet dat je aangepaste authenticatie, ongebruikelijk synchronisatiegedrag, gedetailleerde apparaatverificatie of controle over encryptie op laag niveau nodig hebt, kun je met matrix-nio beginnen om latere problemen met een wrapper te voorkomen. Voor bridges of integraties die routering op homeserverniveau vereisen, kun je beter de Matrix Application Service API raadplegen in plaats van een normaal botaccount als vervanging te gebruiken.

Stap 1: Kies een thuisserver en controleer hoe de bot kan inloggen.

Een Matrix-bot heeft een Matrix-gebruikersaccount nodig op een homeserver. Je kunt een openbare homeserver gebruiken waar het aanmaken van accounts is toegestaan, of een account op een homeserver die je zelf beheert. Houd de bot gescheiden van je persoonlijke Matrix-identiteit, zodat machtigingen, kamerlidmaatschap en inloggegevens onafhankelijk van elkaar beheerd kunnen worden.

De belangrijkste beslissing betreft authenticatie. De huidige Matrix-specificatie ondersteunt zowel de oude authenticatie-API als OAuth 2.0. Een thuisserver kan een van beide of beide beschikbaar stellen. De gepubliceerde snelstartvoorbeelden van Simple-Matrix-Bot-Lib gebruiken een URL, gebruikersnaam en wachtwoord van de thuisserver, dus deze handleiding gaat ervan uit dat uw server nog steeds een compatibele wachtwoordaanmeldingsprocedure biedt.

Controleer voordat je code schrijft welke inlogmethoden je homeserver beschikbaar stelt:

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

Als het antwoord een wachtwoordaanmeldingsproces bevat, is het onderstaande voorbeeld met referenties een goede keuze. Als de server alleen SSO of alleen OAuth ondersteunt, forceer dan geen wachtwoord in het voorbeeld. Controleer in dat geval de authenticatieondersteuning in de huidige bibliotheekversie of gebruik een client op een lager niveau die het benodigde proces ondersteunt. De Matrix-specificatie beschrijft de ontdekking van aanmeldingen en de verwerking van tokens in het gedeelte over aanmeldingen van de Client-Server API .

Stap 2: Maak een geïsoleerde Python-omgeving aan en installeer de bibliotheek.

Gebruik een virtuele omgeving zodat de afhankelijkheden van de bot gescheiden zijn van de systeem-Python en van niet-gerelateerde projecten. De huidige PyPI-metadata vereist Python 3.9 of later.

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

Activeer de omgeving in Windows PowerShell met:

.venv\Scripts\Activate.ps1

Controleer wat er is geïnstalleerd in plaats van uit te gaan van een versie uit een oude handleiding:

python -m pip show simplematrixbotlib

Die versiecontrole is belangrijk omdat de openbare Read the Docs-pagina's nog steeds oudere documentatie tonen en expliciet waarschuwen dat deze mogelijk verouderd is. Als een voorbeeld van die pagina's conflicteert met het geïnstalleerde pakket, controleer dan de release-metadata en de huidige repository voordat u uw code aanpast aan de oudere pagina.

Heeft u end-to-end-versleuteling nodig?

Niet elke bot doet dat. Een bot die alleen deelneemt aan onversleutelde operationele ruimtes is eenvoudiger te implementeren en hoeft de versleutelingsstatus niet te behouden. Een bot die geacht wordt te lezen en te reageren binnen versleutelde ruimtes, heeft extra afhankelijkheden en een permanente versleutelingsstatus nodig.

Zowel de documentatie van Simple-Matrix-Bot-Lib als de huidige documentatie van matrix-nio geven aan dat E2EE afhankelijk is van de encryptieondersteuning van matrix-nio en libolm. Op Debian of Ubuntu beschrijft matrix-nio de installatie libolm-deven vervolgens de E2EE-extra:

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

Schakel E2EE niet in alleen omdat Matrix het ondersteunt. Gebruik het alleen wanneer de kamers versleuteling vereisen en u bereid bent de opslag van de bot te bewaren en het vertrouwen van het apparaat te beheren. De matrix-nio-documentatie vermeldt dat de versleutelingsstatus, sleutels en het vertrouwen van het apparaat lokaal worden opgeslagen wanneer E2EE is ingeschakeld.

Stap 3: Maak het botaccount aan en zorg ervoor dat de inloggegevens niet in de broncode terechtkomen.

Maak een speciaal Matrix-account aan via een client of het accountbeheerproces van uw thuisserver. De exacte registratie-interface verschilt per provider, dus deze handleiding gaat niet uit van een specifiek Element-scherm en beweert niet dat open registratie overal beschikbaar is.

Exporteer voor ontwikkelingsdoeleinden drie omgevingsvariabelen:

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

Omgevingsvariabelen zijn handig voor een lokale tutorial, maar ze vormen niet automatisch een professioneel systeem voor het beheren van geheimen. Gebruik op een VPS of containerplatform de geheimenopslag van het platform zelf, een beveiligd omgevingsbestand buiten versiebeheer of een speciaal daarvoor bestemde geheimenbeheerder. Voeg nooit een Matrix-wachtwoord of toegangstoken toe aan Git.

Nodig het botaccount uit voor een testruimte en accepteer de uitnodiging met een Matrix-client als je server- of botconfiguratie uitnodigingen niet automatisch accepteert. Begin met een privétestruimte. Dit beperkt de kans op onbedoelde commando-uitvoering terwijl je het gedrag van de bot valideert.

Stap 4: Schrijf, voer uit en test een minimale commandobot

Maak het aan bot.pymet een klein !pingcommando. De onderstaande structuur volgt het voorbeeld van het openbare pakket: maak aan Creds, maak aan Bot, voeg een asynchrone berichtlistener toe, gebruik MessageMatchen verstuur een tekstbericht 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()

Voer het uit vanuit de geactiveerde virtuele omgeving:

python bot.py

Stuur in de testruimte het volgende:

!ping

Een succesvol resultaat is eenvoudig: de bot blijft verbonden, ziet de gebeurtenis in de chatruimte en reageert met Pong!. Controleer ook of de bot niet op zijn eigen antwoord reageert. Deze is_not_from_this_bot()controle is belangrijk, omdat een naïeve bot in echo-stijl anders feedbackloops kan creëren.

Wanneer moet je een whitelist toevoegen?

Voeg een commando toe voordat de bot iets gevoeligs kan doen. Een commando dat alleen "Pong!" retourneert, heeft weinig impact, maar een commando dat implementatietaken uitvoert, interne systemen raadpleegt of vertrouwelijke gegevens publiceert, mag niet voor elke gebruiker in elke chatroom worden uitgevoerd.

Simple-Matrix-Bot-Lib presenteert toegangsbeheer voor gebruikers en de configuratie van toegangs-/blokkeerlijsten als functies. Beschouw autorisatie voor een productiebot als applicatielogica, niet als een optionele verfijningsstap. Beperk de toegang op basis van gebruikers-ID, kamer-ID of beide, en behoud server-side machtigingen op de onderliggende systemen als een tweede verdedigingslinie.

Inloggen met wachtwoord versus toegangstokens: wat is de praktische afweging?

Inloggen met een wachtwoord is eenvoudig te begrijpen en komt overeen met het gepubliceerde minimale voorbeeld van het pakket. Het nadeel is dat een bot die langdurig actief is, het accountwachtwoord moet bezitten, en sommige moderne Matrix-implementaties geven mogelijk de voorkeur aan SSO- of OAuth-flows.

Toegangstokens verminderen het herhaaldelijk gebruik van wachtwoorden, maar de regels voor de levenscyclus van tokens zijn afhankelijk van het authenticatiesysteem. De Matrix-specificatie stelt dat toegangstokens moeten worden behandeld als ondoorzichtige referenties en moeten worden verzonden via het HTTP- Authorization: Bearerschema. De huidige Matrix-versies ondersteunen in sommige flows ook verlopende toegangstokens en vernieuwingstokens. Ga er niet van uit dat een voorbeeld dat is geschreven voor wachtwoordreferenties automatisch vernieuwing, intrekking of OAuth afhandelt.

Als de levenscyclus van tokens, SSO, OAuth of authenticatie via serviceaccounts essentieel is voor uw implementatie, controleer dan of deze functionaliteit beschikbaar is in de specifieke Simple-Matrix-Bot-Lib-release die u installeert. Als de wrapper onvoldoende controle biedt, is het rechtstreeks gebruiken van matrix-nio een betere technische oplossing.

Moet je de bot op een laptop, VPS, container of Kubernetes draaien?

Voor een niet-versleutelde, lichtgewicht bot is een kleine VM of container meestal voldoende. Voor een versleutelde bot is persistentie een ontwerpeis: het verlies van de lokale cryptografische opslag kan de apparaatidentiteit wijzigen en het vertrouwen ondermijnen. De E2EE-voorbeelden van matrix-nio benadrukken het behoud van de apparaat-ID en de cryptografische opslag na herstarts.

Veelvoorkomende installatiefouten en wat ze doorgaans betekenen

• Aanmelden mislukt direct: controleer de URL van de homeserver en inspecteer deze /_matrix/client/v3/login. Een server die geen wachtwoordaanmelding adverteert, werkt mogelijk niet met een wachtwoordgebaseerde snelle start.
• De bot start wel, maar ziet geen berichten: controleer of het botaccount daadwerkelijk is aangemeld bij de chatroom en of je test met een normaal tekstbericht.
• De bot antwoordt herhaaldelijk: zorg ervoor dat de handler gebeurtenissen negeert die door de bot zelf worden verzonden.
• Versleutelde kamers zijn onleesbaar: het installeren van het basispakket is niet voldoende. Voeg matrix-nio E2EE-afhankelijkheden toe, schakel versleuteling in volgens de bibliotheekconfiguratie en behoud de cryptografische opslag.
• Een oud voorbeeld geeft een API-fout: controleer de versie van uw geïnstalleerde pakket. De openbare documentatie van Simple-Matrix-Bot-Lib waarschuwt momenteel dat deze niet meer wordt onderhouden, waardoor voorbeelden mogelijk achterlopen op de PyPI-release.

Welk pad moet je kiezen?

Kies Simple-Matrix-Bot-Lib als uw bot slechts één Matrix-gebruiker is, uw commando's eenvoudig zijn en u meer waarde hecht aan beknopte Python-code dan aan controle over protocollen op laag niveau. Het is met name geschikt voor prototypes, notificatiebots, room utility's en kleine interne automatiseringen.

Kies direct voor matrix-nio wanneer encryptie, apparaatverificatie, aangepaste authenticatie, gebeurtenistypen, synchronisatiegedrag of tokenbeheer essentiële vereisten zijn. U zult meer code schrijven, maar de abstractiedrempel is lager en het is gemakkelijker te begrijpen voor geavanceerd Matrix-werk.

Kies voor een applicatieservice wanneer uw integratie feitelijk een homeserver-extensie, bridge of gateway is, in plaats van een bot voor één gebruiker. De API van de applicatieservice is ontworpen voor dat servergekoppelde model en vereist configuratie op de homeserver.

Voor een eerste Matrix-bot !pingis het minimale voorbeeld een goede eerste stap: als de bot kan authenticeren, de juiste ruimte kan betreden, zijn eigen gebeurtenissen kan negeren en betrouwbaar kan reageren, dan heb je het basispad gevalideerd. Voeg encryptie, autorisatie, externe API's en implementatieautomatisering pas toe nadat die basis stabiel is.

Primaire referenties

• Simple-Matrix-Bot-Lib op PyPI — actuele pakketmetadata, Python-vereisten, releasegeschiedenis en een basisvoorbeeld.
• De documentatie van Simple-Matrix-Bot-Lib is een handig naslagwerk over het gebruik ervan; de website waarschuwt momenteel dat deze mogelijk verouderd is.
• Matrix-Nio-documentatie — onderliggende clientbibliotheek, end-to-end-afhankelijkheden, opslag en voorbeelden.
• Matrix Client-Server API — huidig ​​gedrag van authenticatie-, inlog-, token-, room- en eventprotocollen.
• Matrix Application Service API — een servergeïntegreerd alternatief voor bridges en grotere integraties.