Integración domótica Matrix, gratuita y de código abierto

Hable con Gladys desde Matrix, escriba en salas y lance escenas con mensajes o comandos.

• Publicado por guim31
• Mensajería
• Versión 1.0.1
• Requiere Gladys >=5.1.0
• ★ 0

Ver en GitHubTodas las integraciones

Hable con Gladys desde Matrix, la mensajería abierta y descentralizada (Element, FluffyChat, Cinny…), como con el bot de Telegram de Gladys: haga una pregunta, lance una escena, reciba los mensajes de Gladys. La integración también escribe en salas de Matrix desde sus escenas, y lanza escenas cuando se escribe un mensaje o un comando como !luces off en una sala que vigila. Usa una cuenta de bot dedicada, en su propio servidor (Synapse, Conduit, conduwuit, Dendrite…) o en uno público como matrix.org.

Desarrollada sin el hardware: sus comentarios son bienvenidos. La integración se ha probado con un servidor Conduit 0.10 real, pero no dentro de un Gladys real ni con todos los clientes de Matrix. Cuente lo que funciona y lo que no en las issues o en el foro de Gladys.

Lo que necesita

• Gladys Assistant 5.1.0 o posterior.
• Una cuenta de Matrix dedicada al bot (por ejemplo @gladys:example.org), en un servidor que Gladys pueda alcanzar: su servidor en la red local, o uno público en Internet. No use su cuenta personal: el bot responde en su nombre.
• Salas sin cifrado de extremo a extremo. El bot no puede leer las salas cifradas (Element cifra por defecto las salas privadas y los mensajes directos: desactive la opción al crear la sala, después ya no se puede cambiar).
• El identificador Matrix de cada persona autorizada a hablar con el bot, como @alice:example.org.

Puesta en marcha

1. Cree la cuenta del bot (en matrix.org: un registro normal; en su servidor: como las demás cuentas).
2. En Gladys, Integraciones → Matrix → Configuración:
   • Dirección del servidor Matrix: la API cliente del servidor, por ejemplo https://matrix.org o http://192.168.1.20:8008. Para un servidor detrás de su nombre de dominio, suele ser https://matrix. seguido del dominio.
   • Usuario del bot y Contraseña del bot: el bot inicia sesión una vez y guarda su token de acceso en los datos de la integración. O rellene Token de acceso (en lugar de la contraseña) con un token de la cuenta del bot: entonces no se usan el usuario ni la contraseña.
   • Personas autorizadas: los identificadores Matrix que el bot escucha, separados por comas. Vacío, el bot no responde a nadie: ignora los mensajes y las invitaciones de quien no esté en esta lista.
   • Salas vigiladas: las salas cuyos mensajes lanzan escenas, por alias (#casa:example.org) o por identificador (!abc…:example.org, en los ajustes de la sala, «Avanzado»), separadas por comas. Invite primero al bot a una sala privada: entra por sí solo en las salas de esta lista.
   • Prefijo de los comandos: ! por defecto.
   • Idioma del bot: el idioma de lo que escribe el bot antes de vincular a una persona.
3. Pulse Probar la conexión: el informe indica la cuenta del bot, las salas vigiladas en las que ha entrado y el número de personas autorizadas. El estado de conexión de la página también lo muestra.

Vincular su cuenta Matrix para hablar con Gladys

Cada usuario de Gladys que quiera hablar con Gladys desde Matrix lo hace una vez:

1. En Matrix, cree una sala privada sin cifrado e invite al bot (solo personas autorizadas: el bot ignora las invitaciones de los demás). Entra enseguida.
2. En Gladys, Integraciones → Matrix → Configuración, bloque «Vincular mi cuenta»: pulse Generar un código de vinculación.
3. Envíe el código (8 caracteres) al bot en esa sala. El bot lo confirma: su cuenta Matrix está vinculada a su usuario de Gladys. Puede desvincularla desde el mismo bloque.

Lo que hace el bot

• En una sala privada (una sala solo con usted y el bot, que no sea una sala vigilada; en una sala de grupo no vigilada, el bot no dice nada): transmite sus mensajes a Gladys, con la autoridad del usuario de Gladys vinculado, igual que el bot de Telegram: «¿Qué temperatura hace en el salón?», «Apaga las luces». Las respuestas de Gladys vuelven a esa sala. Los mensajes que Gladys le envía (la acción de escena Enviar mensaje, los mensajes del sistema) también llegan allí, con el Markdown representado. Si Gladys escribe a una persona vinculada antes de cualquier conversación, el bot abre con ella una sala privada sin cifrar. Una imagen de cámara enviada por una escena llega como imagen.
• En una sala vigilada: cada mensaje de una persona autorizada lanza el desencadenante Mensaje Matrix recibido, y un mensaje que empieza por el prefijo lanza además Comando Matrix recibido. El bot nunca responde ahí por sí mismo: lo que ocurre depende de sus escenas.
• Lo que ignora: a quien no sea una persona autorizada, sus propios mensajes, las ediciones de un mensaje, los avisos (lo que escriben otros bots) y los mensajes con más de 5 minutos cuando los lee (escritos mientras Gladys o el bot estaban detenidos: un «!abrir garaje» de hace dos horas no se ejecuta ahora).
• En una sala cifrada: no puede leer el mensaje y lo dice una vez en esa sala.

Panel

El widget Matrix muestra si el bot está conectado, su cuenta, las salas vigiladas en las que está, los 5 últimos mensajes recibidos en las salas vigiladas (autor, texto, fecha) y un botón Probar la conexión. Las conversaciones privadas con Gladys nunca aparecen: todos los que ven el panel ven el widget.

Escenas

Desencadenantes

• Mensaje Matrix recibido: una persona autorizada ha escrito en una sala vigilada. Filtros (vacío = cualquiera): Sala (escrita como en la configuración, por ejemplo #casa:example.org) y Remitente (@alice:example.org). Variables: Mensaje, Remitente, Sala, Identificador de la sala.
• Comando Matrix recibido: una persona autorizada ha escrito un comando en una sala vigilada: el prefijo, luego una palabra y luego argumentos opcionales, por ejemplo !luces off cocina. Filtro Comando: la palabra sin el prefijo, en minúsculas (luces); y Sala, Remitente. Variables: Comando (luces), Argumentos (off cocina), Mensaje, Remitente, Sala, Identificador de la sala. El mismo mensaje lanza también Mensaje Matrix recibido.
• Conexión Matrix perdida: el bot ya no alcanza el servidor Matrix desde hace un minuto, o sus credenciales son rechazadas. Variable: Error. Se lanza una vez, hasta que vuelve la conexión.
• Conexión Matrix restablecida: el bot vuelve a alcanzar el servidor tras una pérdida de conexión. Variable: Cuenta del bot.

Acciones

• Enviar un mensaje Matrix: escribe un mensaje en una sala, por alias o identificador. El mensaje admite las variables de escena y Markdown (**negrita**, _cursiva_, listas, enlaces). Discreto (aviso, sin alerta) envía un aviso, que los clientes de Matrix muestran sin alerta. El bot debe estar en la sala, o poder entrar en ella (invitado, o sala pública). Resultados: Enviado (sí/no), Identificador del evento, Error. Un mensaje fallido no detiene la escena: compruebe Enviado con una condición si hace falta.

Para escribir a un usuario de Gladys en lugar de a una sala, use la acción Enviar mensaje de Gladys: llega a su cuenta Matrix vinculada.

Ideas de escenas

• Garaje por comando: desencadenante Comando Matrix recibido, comando garaje, sala #casa:example.org; luego una condición sobre la variable Argumentos igual a cerrar, y la acción que cierra el garaje.
• Timbre en la sala de la familia: desencadenante en el timbre, luego Enviar un mensaje Matrix a #casa:example.org: «Han llamado a las {{ hora }}», seguido de la acción del núcleo que envía la imagen de la cámara a un usuario.
• Alerta cuando el bot se desconecta: desencadenante Conexión Matrix perdida, luego una notificación por otro canal (Gotify, ntfy, SMS) con la variable Error.

Solución de problemas

• «no hay servidor Matrix en esta dirección»: la dirección es la de la API cliente, no la página del cliente web Element. Abra https://<dirección>/_matrix/client/versions en un navegador: debe responder una lista de versiones.
• «usuario o contraseña del bot rechazados»: compruébelos iniciando sesión con la cuenta del bot en Element. Una cuenta protegida solo por inicio de sesión único (SSO) no tiene contraseña: use un token de acceso.
• «token de acceso rechazado»: el token fue revocado (cierre de esa sesión) o caducó. Introduzca uno nuevo, o el usuario y la contraseña.
• No ha entrado en una sala vigilada: el estado de la página y la prueba la nombran. Invite al bot a la sala (o hágala pública) y vuelva a guardar la configuración.
• El bot no me responde: ¿está su identificador Matrix en Personas autorizadas, escrito exactamente (con la @ y el servidor)? ¿La sala no está cifrada? En una sala privada, ¿está vinculada su cuenta (si no, el bot le da las instrucciones)?
• Un comando no lanza la escena: el filtro Comando es la palabra sin el prefijo, en minúsculas: luces, no !Luces.
• Más detalles en los registros de la integración con LOG_LEVEL=debug.

Límites

• Sin cifrado de extremo a extremo: el bot solo lee y escribe en salas sin cifrar. Sus mensajes viajan cifrados entre su cliente, el servidor y Gladys (HTTPS), pero se guardan legibles en el servidor Matrix.
• Una persona vinculada a Gladys puede hacer desde Matrix todo lo que puede su usuario de Gladys: mantenga corta la lista de personas autorizadas y proteja la cuenta del bot (contraseña robusta, nunca reutilizada).
• Una cuenta de bot por Gladys. El bot lee los mensajes con una escucha larga de 30 segundos: un comando surte efecto en un segundo aproximadamente.
• Las imágenes, archivos y mensajes de voz enviados al bot se ignoran; solo cuenta el texto.
• La cuenta del bot está sujeta a los límites de envío de su servidor: matrix.org frena las cuentas que envían mucho, mantenga escenas razonables.
• Sin relación con la Fundación Matrix.org. Matrix es una marca de The Matrix.org Foundation C.I.C.

Parámetros de configuración

Estos son los parámetros que Matrix te pide en su pantalla de configuración en Gladys.

Parámetro	Tipo	Obligatorio	Descripción
Para empezar	section	No	Cree una cuenta Matrix dedicada al bot, en su servidor o en matrix.org. Las salas no deben tener cifrado de extremo a extremo: el bot no puede leer las salas cifradas.
Dirección del servidor Matrix	string	Sí	La API cliente del servidor, p. ej. https://matrix.org o http://192.168.1.20:8008.
Usuario del bot	string	No	Para iniciar sesión con contraseña: el usuario o el identificador completo de la cuenta del bot.
Contraseña del bot	secret	No	Sirve una vez para obtener un token de acceso, guardado en los datos de la integración.
Token de acceso (en lugar de la contraseña)	secret	No	Opcional: el token de acceso de la cuenta del bot. Si se indica, no se usan el usuario ni la contraseña.
Personas autorizadas	string	No	Identificadores Matrix que el bot escucha, separados por comas, p. ej. @alice:example.org. Vacío: el bot no responde a nadie.
Salas vigiladas	string	No	Salas cuyos mensajes activan escenas, por alias o identificador, separadas por comas. El bot entra en ellas (invítelo a una sala privada).
Prefijo de los comandos	string	No	Un mensaje que empieza por él es un comando, p. ej. !luces off. De uno a tres caracteres.
Idioma del bot	select	No	Idioma de lo que escribe el bot antes de vincular a una persona, y de los informes.

Cómo instalar Matrix en Gladys

1. En Gladys, abre Integraciones: Matrix aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/guim31/gladys-matrix:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-matrix.

Matrix requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas

Matrix es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.

• Explorar todas las integraciones, nativas y de la comunidad
• Crear y publicar tu propia integración externa
• Código fuente en GitHub — fuente de esta documentación

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂