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

Hable con Gladys desde Mattermost, escriba en canales 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 Mattermost, el chat de equipo libre que puede alojar usted mismo, como con el bot de Telegram de Gladys: haga una pregunta, lance una escena, reciba los mensajes de Gladys en un mensaje directo. La integración también escribe en canales de Mattermost desde sus escenas, y lanza escenas cuando se escribe un mensaje o un comando como !luces off en un canal que vigila. Usa una cuenta de bot de su servidor Mattermost, en la red local o en Internet.

Desarrollada sin el hardware: se agradecen sus comentarios. La integración se ha probado con un servidor Mattermost real (Team Edition, en Docker), pero no dentro de un Gladys real ni con todos los clientes de Mattermost. Indique lo que funciona y lo que no en las issues o en el foro de Gladys.

Requisitos

• Gladys Assistant 5.1.0 o posterior.
• Un servidor Mattermost al que Gladys pueda llegar (versión 7 o posterior), y una cuenta de administrador para crear el bot.
• Una cuenta de bot (o un usuario dedicado con un token de acceso personal). No use su cuenta personal: el bot responde en su nombre.
• El nombre de usuario de cada persona autorizada a hablar con el bot, por ejemplo alice.

Configuración

1. En Mattermost, Consola del sistema → Integraciones → Cuentas de bot: active Habilitar la creación de cuentas de bot.
2. Menú principal Integraciones → Cuentas de bot → Añadir cuenta de bot: un nombre de usuario como gladys, el rol Miembro. Copie el token que se muestra una sola vez al final.
3. Añada el bot a su equipo (menú del equipo Añadir miembros, o Consola del sistema → Usuarios).
4. En Gladys, Integraciones → Mattermost → Configuración:
   • Dirección del servidor: la dirección de Mattermost como en el navegador, por ejemplo https://chat.example.org o http://192.168.1.20:8065.
   • Token del bot: el token del paso 2.
   • Personas autorizadas: los nombres de usuario que el bot escucha, separados por comas (alice, bob). Vacío, el bot no responde a nadie: ignora los mensajes de todos los que no están en esta lista.
   • Canales vigilados: los canales cuyos mensajes lanzan escenas, escritos equipo/canal como en su dirección (https://chat.example.org/casa/channels/garaje da casa/garaje; también se acepta la dirección completa), o por identificador de canal, separados por comas. El bot se une solo a los canales públicos; añádalo antes a los privados.
   • Prefijo de los comandos: ! por defecto (/ lo usan los comandos slash de Mattermost).
   • Idioma del bot: el idioma de lo que escribe el bot antes de vincular a una persona.
5. Pulse Probar la conexión: el informe indica la cuenta del bot, los canales vigilados a los que se ha unido y las personas autorizadas encontradas. El estado de conexión de la página también lo indica, y nombra un canal o una persona que no se ha encontrado.

Vincular su cuenta Mattermost para hablar con Gladys

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

1. En Gladys, Integraciones → Mattermost → Configuración, bloque «Vincular mi cuenta»: pulse Generar un código de vinculación.
2. En Mattermost, abra un mensaje directo con el bot (el + junto a «Mensajes directos», y luego su nombre de usuario) y envíele el código (8 caracteres). El bot lo confirma: su cuenta Mattermost está vinculada a su usuario de Gladys. Puede desvincularla desde el mismo bloque.

Qué hace el bot

• En un mensaje directo con una persona autorizada: transmite los mensajes a Gladys, con los permisos del usuario de Gladys vinculado, exactamente como el bot de Telegram: «¿Qué temperatura hace en el salón?», «Apaga las luces». Las respuestas de Gladys vuelven a este mensaje directo, con el Markdown mostrado por Mattermost. Los mensajes que Gladys le envía (la acción de escena Enviar un mensaje, los mensajes del sistema) también llegan allí, incluso antes de cualquier conversación. Una imagen de cámara enviada por una escena llega como imagen.
• En un canal vigilado: cada mensaje de una persona autorizada lanza el disparador Mensaje Mattermost recibido, y un mensaje que empieza por el prefijo lanza además Comando Mattermost recibido. El bot nunca responde allí por sí mismo: lo que ocurra depende de sus escenas.
• En cualquier otro canal (un mensaje de grupo, un canal no vigilado): se calla. Gladys nunca responde donde otros pueden leer.
• Lo que ignora: a toda persona no autorizada, sus propios mensajes (una escena que escribe en un canal vigilado nunca se vuelve a lanzar a sí misma), los mensajes del sistema («se ha unido al canal»), las ediciones, y los mensajes de más de 5 minutos cuando los lee (un «!abre garaje» de hace dos horas no se ejecuta ahora).
• Tras un corte (reinicio del servidor, de Gladys, una caída breve de la red): se vuelve a conectar solo, y relee los mensajes de los canales vigilados y de los mensajes directos escritos en los últimos 5 minutos.

Panel

El widget Mattermost muestra si el bot está conectado, su cuenta, los canales vigilados en los que está, los 5 últimos mensajes recibidos en los canales vigilados (autor, texto, fecha) y un botón Probar la conexión. Los mensajes directos con Gladys nunca aparecen: todos los que ven el panel ven el widget.

Escenas

Disparadores

• Mensaje Mattermost recibido: una persona autorizada ha escrito en un canal vigilado. Filtros (vacío = cualquiera): Canal (escrito como en la configuración, por ejemplo casa/garaje) y Remitente (el nombre de usuario, sin @: alice). Variables: Mensaje, Remitente, Canal, Identificador del canal.
• Comando Mattermost recibido: una persona autorizada ha escrito un comando en un canal vigilado: el prefijo, luego una palabra, luego argumentos opcionales, por ejemplo !luces off cocina. Filtro Comando: la palabra sin el prefijo, en minúsculas (luces); y Canal, Remitente. Variables: Comando (luces), Argumentos (off cocina), Mensaje, Remitente, Canal, Identificador del canal. El mismo mensaje lanza también Mensaje Mattermost recibido.
• Conexión Mattermost perdida: el bot ya no alcanza el servidor, desde hace un minuto, o su token es rechazado. Variable: Error. Se lanza una vez, hasta que vuelve la conexión.
• Conexión Mattermost restablecida: el bot vuelve a alcanzar el servidor tras una pérdida de conexión. Variable: Cuenta del bot (nombre de usuario).

Acciones

• Enviar un mensaje Mattermost: escribe un mensaje en un canal (equipo/canal, su dirección o su identificador), o a una persona en un mensaje directo (@alice). El mensaje acepta las variables de escena y el Markdown de Mattermost (**negrita**, _cursiva_, listas, enlaces, @here). El bot debe estar en el canal, o poder unirse a él (un canal público de su equipo). Resultados: Enviado (sí/no), Identificador del mensaje, Error. Un mensaje fallido no detiene la escena: compruebe Enviado con una condición si hace falta.

Para escribir a un usuario de Gladys, también sirve la acción Enviar un mensaje de Gladys: llega a su cuenta Mattermost vinculada.

Ideas de escenas

• Garaje por comando: disparador Comando Mattermost recibido, comando garaje, canal casa/garaje; luego una condición sobre la variable Argumentos igual a cerrar, y la acción que cierra el garaje.
• Lavadora terminada: cuando baja la potencia del enchufe de la lavadora, Enviar un mensaje Mattermost a casa/familia: «La lavadora ha terminado @here».
• Alerta cuando el bot está desconectado: disparador Conexión Mattermost perdida, luego una notificación por otro canal (Gotify, ntfy, SMS) con la variable Error.

Solución de problemas

• «no hay servidor Mattermost en esta dirección»: use la dirección con la que abre Mattermost en el navegador, sin /login ni el equipo. https://<dirección>/api/v4/system/ping debe responder {"status":"OK"…}.
• «token de acceso rechazado»: el token se ha revocado, o la cuenta del bot se ha desactivado. Cree un token nuevo en Integraciones → Cuentas de bot.
• No se ha unido a un canal vigilado: el estado de la página y la prueba lo nombran. Compruebe los nombres del equipo y del canal en la dirección del canal, añada el bot al equipo, y al canal si es privado, y vuelva a guardar la configuración.
• El bot no me responde: ¿está su nombre de usuario en Personas autorizadas, escrito exactamente? ¿Le escribe en un mensaje directo (no en un mensaje de grupo)? ¿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.
• Detrás de un proxy inverso, también hay que reenviar el WebSocket (/api/v4/websocket), como para las aplicaciones de Mattermost.
• Más detalles en los registros de la integración con LOG_LEVEL=debug.

Limitaciones

• Una persona vinculada a Gladys puede hacer desde Mattermost todo lo que puede hacer su usuario de Gladys: mantenga corta la lista de personas autorizadas, y secreto el token del bot.
• Una cuenta de bot por Gladys. El bot lee los mensajes por el WebSocket de Mattermost: un comando surte efecto en un segundo aproximadamente. Los mensajes perdidos durante un corte de más de 5 minutos se omiten.
• Los archivos, imágenes y mensajes de voz enviados al bot se ignoran; solo cuenta el texto. Los hilos se leen como mensajes normales, y las respuestas de Gladys no van al hilo.
• El bot está sujeto a los límites de velocidad de la API del servidor (10 solicitudes por segundo y por cuenta por defecto): mantenga razonables los mensajes de sus escenas.
• Sin relación con Mattermost, Inc. Mattermost es una marca de Mattermost, Inc.

Parámetros de configuración

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

Parámetro	Tipo	Obligatorio	Descripción
Para empezar	section	No	Cree una cuenta de bot en Mattermost (Consola del sistema → Integraciones → Cuentas de bot), añádala a su equipo y copie su token. Después, escríbale un mensaje directo.
Dirección del servidor	string	Sí	La dirección de su Mattermost, como en el navegador, p. ej. https://chat.example.org o http://192.168.1.20:8065.
Token del bot	secret	No	El token de acceso de la cuenta de bot (o un token de acceso personal de una cuenta dedicada).
Personas autorizadas	string	No	Nombres de usuario que el bot escucha, separados por comas, p. ej. alice, bob. Vacío: el bot no responde a nadie.
Canales vigilados	string	No	Canales cuyos mensajes activan escenas, como equipo/canal (como en su dirección) o por identificador, separados por comas. El bot se une a los canales públicos; añádalo a los privados.
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 Mattermost en Gladys

1. En Gladys, abre Integraciones: Mattermost 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-mattermost: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-mattermost.

Mattermost 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

Mattermost 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 🙂