Cómo configurar un bot de matriz con Python y la biblioteca Simple-Matrix-Bot-Lib.

¿Qué es lo que realmente estás eligiendo cuando construyes un bot de Matrix de esta manera?

Simple-Matrix-Bot-Lib es una capa de conveniencia sobre la matrix-niobiblioteca cliente de Python. Esto la hace atractiva cuando se necesita un pequeño bot de comandos, un bot de notificaciones o un asistente para salas sin tener que escribir todo el bucle de sincronización y manejo de eventos de Matrix. La contrapartida es que se aceptan las abstracciones y los patrones de autenticación que ofrece la capa en lugar de controlar directamente cada detalle del cliente Matrix.

A fecha de 6 de octubre de 2026, PyPI incluye la versión simplematrixbotlib2.13.1, publicada el 29 de marzo de 2026, que requiere Python 3.9 o superior, pero anterior a Python 4. El sitio web Read the Docs del proyecto advierte actualmente de que su documentación no recibe mantenimiento y puede estar desactualizada, por lo que esta guía utiliza PyPI y la especificación actual de Matrix como referencias principales y considera la documentación antigua como una guía de implementación en lugar de una prueba del comportamiento actual.

Para obtener información sobre el paquete, consulte el proyecto simplematrixbotlib en PyPI . Para conocer el comportamiento del protocolo, utilice la especificación actual de la API cliente-servidor de Matrix .

¿Simple-Matrix-Bot-Lib, matrix-nio o un servicio de aplicación?

Si tu objetivo es "responder a comandos en salas como una sola cuenta de bot", Simple-Matrix-Bot-Lib suele ser la opción más sencilla. Si ya sabes que necesitas autenticación personalizada, un comportamiento de sincronización inusual, verificación detallada del dispositivo o control de cifrado de bajo nivel, empezar con matrix-nio puede evitarte problemas con un wrapper más adelante. Para puentes o integraciones que requieren enrutamiento a nivel de servidor principal, consulta la API del Servicio de Aplicaciones de Matrix en lugar de usar una cuenta de bot normal como sustituto.

Paso 1: Elija un servidor principal y confirme cómo puede iniciar sesión el bot.

Un bot de Matrix necesita una cuenta de usuario de Matrix en un servidor doméstico. Puedes usar un servidor doméstico público que permita la creación de cuentas o una cuenta en un servidor doméstico que administres. Mantén el bot separado de tu identidad personal de Matrix para que los permisos, la pertenencia a salas y las credenciales se puedan gestionar de forma independiente.

La decisión clave es la autenticación. La especificación actual de Matrix admite tanto la API de autenticación heredada como OAuth 2.0. Un servidor doméstico puede exponer una o ambas. Los ejemplos de inicio rápido publicados por Simple-Matrix-Bot-Lib utilizan una URL de servidor doméstico, un nombre de usuario y una contraseña, por lo que este tutorial asume que su servidor aún ofrece un flujo de inicio de sesión con contraseña compatible.

Antes de escribir código, compruebe los métodos de inicio de sesión que expone su servidor doméstico:

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

Si la respuesta incluye un flujo de inicio de sesión con contraseña, el ejemplo basado en credenciales que se muestra a continuación es adecuado. Si el servidor solo admite SSO o OAuth, no fuerce el uso de una contraseña en el ejemplo. En ese caso, confirme la compatibilidad con la autenticación en la versión actual de la biblioteca o utilice un cliente de nivel inferior que admita el flujo que necesita. La especificación Matrix explica la detección de inicio de sesión y el manejo de tokens en la sección de inicio de sesión de la API Cliente-Servidor .

Paso 2: Crea un entorno Python aislado e instala la biblioteca.

Utilice un entorno virtual para que las dependencias del bot estén separadas del Python del sistema y de proyectos no relacionados. Los metadatos actuales de PyPI requieren Python 3.9 o posterior.

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

En Windows PowerShell, active el entorno con:

.venv\Scripts\Activate.ps1

Verifica qué versión se instaló en lugar de asumir una versión a partir de un tutorial antiguo:

python -m pip show simplematrixbotlib

Esta comprobación de versión es importante porque las páginas públicas de «Lee la documentación» aún muestran documentación antigua y advierten explícitamente que podría estar desactualizada. Si un ejemplo de esas páginas entra en conflicto con el paquete instalado, revisa los metadatos de la versión y el repositorio actual antes de modificar tu código para que coincida con la página anterior.

¿Necesita cifrado de extremo a extremo?

No todos los bots lo hacen. Un bot que solo se une a salas operativas no cifradas es más sencillo de implementar y no necesita mantener el estado de cifrado. Un bot que debe leer y responder dentro de salas cifradas requiere dependencias adicionales y un estado criptográfico persistente.

La documentación de Simple-Matrix-Bot-Lib y la documentación actual de matrix-nio indican que E2EE depende del soporte de cifrado de matrix-nio y de libolm. En Debian o Ubuntu, matrix-nio documenta la instalación libolm-devy luego el complemento E2EE:

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

No actives el cifrado de extremo a extremo solo porque Matrix lo admita. Úsalo cuando las salas requieran cifrado y estés preparado para almacenar los datos del bot y gestionar la confianza del dispositivo. La documentación de matrix-nio indica que el estado del cifrado, las claves y la confianza del dispositivo se almacenan localmente cuando se activa el cifrado de extremo a extremo.

Paso 3: Crea la cuenta del bot y mantén las credenciales fuera del código fuente.

Crea una cuenta Matrix dedicada utilizando un cliente o el proceso de administración de cuentas que ofrece tu servidor. La interfaz de registro varía según el proveedor, por lo que esta guía no presupone una pantalla de Element específica ni afirma que el registro abierto esté disponible en todas partes.

Para el desarrollo, exporte tres variables de entorno:

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

Las variables de entorno son útiles para un tutorial local, pero no constituyen automáticamente un sistema de gestión de secretos apto para producción. En una plataforma VPS o de contenedores, es preferible usar el almacén de secretos de la plataforma, un archivo de entorno protegido fuera del control de versiones o un gestor de secretos dedicado. Nunca incluyas una contraseña de Matrix ni un token de acceso en Git.

Si la configuración de tu servidor o bot no permite unirse automáticamente a las invitaciones, invita a la cuenta del bot a una sala de pruebas y acepta la invitación con un cliente Matrix. Empieza con una sala de pruebas privada. Esto limita la ejecución accidental de comandos mientras validas el comportamiento del bot.

Paso 4: Escribe, ejecuta y prueba un bot de comandos mínimo.

Cree bot.pycon un pequeño !pingcomando. La estructura que se muestra a continuación sigue el ejemplo del paquete público: cree Creds, cree Bot, agregue un oyente de mensajes asíncrono, use MessageMatchy envíe un mensaje de texto a través de 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()

Ejecútalo desde el entorno virtual activado:

python bot.py

En la sala de pruebas, envíe:

!ping

Un resultado exitoso es sencillo: el bot permanece conectado, detecta el evento de la sala y responde Pong!. Confirma también que no responda a su propia respuesta. Esta is_not_from_this_bot()verificación es importante porque, de lo contrario, un bot ingenuo de tipo eco podría generar bucles de retroalimentación.

¿Cuándo se debe agregar una lista de permitidos?

Añade una restricción antes de que el bot pueda activar algo sensible. Un comando que solo devuelva "¡Pong!" tiene poco impacto, pero un comando que ejecute tareas de implementación, consulte sistemas internos o publique datos confidenciales no debería ejecutarse para todos los usuarios en todas las salas a las que se haya unido.

Simple-Matrix-Bot-Lib anuncia la gestión de acceso de usuarios y la configuración de listas de permisos/bloqueos como funcionalidades. Para un bot en producción, considere la autorización como lógica de aplicación, no como un paso opcional de acabado. Restrinja el acceso por ID de usuario, ID de sala o ambos, y mantenga los permisos del servidor en los sistemas posteriores como una segunda línea de defensa.

Inicio de sesión mediante contraseña frente a tokens de acceso: ¿cuál es la ventaja o desventaja práctica?

El inicio de sesión mediante contraseña es fácil de entender y coincide con el ejemplo mínimo publicado en el paquete. La desventaja es que un bot que se ejecuta durante mucho tiempo debe tener la contraseña de la cuenta, y algunas implementaciones modernas de Matrix pueden preferir los flujos SSO u OAuth.

Los tokens de acceso reducen el uso repetido de contraseñas, pero las reglas del ciclo de vida de los tokens dependen del sistema de autenticación. La especificación Matrix indica que los tokens de acceso deben tratarse como credenciales opacas y enviarse mediante el Authorization: Beareresquema HTTP. Las versiones actuales de Matrix también admiten tokens de acceso con caducidad y tokens de actualización en algunos flujos. No asuma que un ejemplo escrito para credenciales de contraseña gestiona automáticamente la actualización, la revocación o OAuth.

Si el ciclo de vida del token, el inicio de sesión único (SSO), OAuth o la autenticación de estilo cuenta de servicio son fundamentales para su implementación, verifique esta funcionalidad en la versión exacta de Simple-Matrix-Bot-Lib que instale. Si el envoltorio no ofrece suficiente control, usar matrix-nio directamente es la opción de ingeniería más limpia.

¿Debería ejecutar el bot en un portátil, un VPS, un contenedor o Kubernetes?

Para un bot ligero sin cifrar, una máquina virtual o contenedor pequeño suele ser suficiente. Para un bot cifrado, la persistencia se convierte en un requisito de diseño: perder el almacén criptográfico local puede cambiar la identidad del dispositivo y afectar la confianza. Los ejemplos de cifrado de extremo a extremo de matrix-nio hacen hincapié en la preservación del ID del dispositivo y el almacén de cifrado tras los reinicios.

Errores comunes en la configuración y lo que suelen significar.

• El inicio de sesión falla inmediatamente: confirme la URL del servidor principal e inspeccione /_matrix/client/v3/login. Un servidor que no anuncia el inicio de sesión con contraseña puede no funcionar con un inicio rápido basado en contraseña.
• El bot se inicia pero nunca recibe mensajes: confirme que la cuenta del bot está realmente unida a la sala y que está realizando la prueba con un evento de texto normal.
• El bot responde repetidamente: asegúrese de que el controlador ignore los eventos enviados por el propio bot.
• Las salas cifradas son ilegibles: instalar el paquete base no es suficiente. Añada las dependencias E2EE de matrix-nio, habilite el cifrado según la configuración de la biblioteca y conserve el almacén criptográfico.
• Un ejemplo antiguo genera un error de API: compruebe la versión del paquete instalado. La documentación pública de Simple-Matrix-Bot-Lib advierte que actualmente no recibe mantenimiento, por lo que los ejemplos pueden estar desactualizados con respecto a la versión de PyPI.

¿Qué camino deberías elegir?

Elige Simple-Matrix-Bot-Lib si tu bot es un único usuario de Matrix, tus comandos son sencillos y valoras más un código Python conciso que un control de protocolo de bajo nivel. Es especialmente adecuado para prototipos, bots de notificación, utilidades para salas y pequeñas automatizaciones internas.

Elija matrix-nio directamente cuando el cifrado, la verificación de dispositivos, la autenticación personalizada, los tipos de eventos, el comportamiento de sincronización o la gestión de tokens sean requisitos fundamentales. Escribirá más código, pero el nivel de abstracción es menor y resulta más fácil de comprender para tareas avanzadas con Matrix.

Elija un Servicio de Aplicación cuando su integración sea realmente una extensión, puente o puerta de enlace del servidor principal, en lugar de un bot para un solo usuario. La API del Servicio de Aplicación está diseñada para ese modelo conectado al servidor y requiere la configuración del servidor principal.

Para un primer bot de Matrix, el !pingejemplo mínimo es un buen punto de referencia: si puede autenticarse, unirse a la sala correcta, ignorar sus propios eventos y responder de forma fiable, habrá validado la ruta básica. Añada cifrado, autorización, API externas y automatización de la implementación solo después de que esta base sea estable.

Referencias primarias

• Simple-Matrix-Bot-Lib en PyPI : metadatos del paquete, requisitos de Python, historial de versiones y ejemplo básico.
• Documentación de Simple-Matrix-Bot-Lib : útil referencia histórica de uso; el sitio advierte actualmente que puede estar desactualizada.
• Documentación de matrix-nio : biblioteca cliente subyacente, dependencias E2EE, almacenamiento y ejemplos.
• API cliente-servidor de Matrix : comportamiento actual de los protocolos de autenticación, inicio de sesión, token, sala y eventos.
• API de Matrix Application Service : alternativa integrada en el servidor para puentes e integraciones de mayor envergadura.