Zum Hauptinhalt springen

Mattermost Smart-Home-Integration, kostenlos und Open Source

Mattermost-Integration für Gladys Assistant

Sprich mit Gladys über Mattermost, schreib in Kanäle, starte Szenen bei Nachrichten oder Befehlen.

Auf GitHub ansehenAlle Integrationen

Sprich mit Gladys über Mattermost, den freien Team-Chat, den du selbst hosten kannst, so wie mit dem Telegram-Bot von Gladys: Stell eine Frage, starte eine Szene, empfange die Nachrichten von Gladys als Direktnachricht. Die Integration schreibt außerdem aus deinen Szenen in Mattermost-Kanäle und startet Szenen, wenn eine Nachricht oder ein Befehl wie !licht aus in einem beobachteten Kanal geschrieben wird. Dafür dient ein Bot-Konto deines Mattermost-Servers, im lokalen Netz oder im Internet.

Ohne die Hardware entwickelt: Rückmeldungen willkommen. Die Integration wurde gegen einen echten Mattermost-Server (Team Edition, in Docker) getestet, aber nicht in einem echten Gladys und nicht mit allen Mattermost-Clients. Melde, was funktioniert und was nicht, in den Issues oder im Gladys-Forum.

Voraussetzungen​

  • Gladys Assistant 5.1.0 oder neuer.
  • Ein Mattermost-Server, den Gladys erreicht (Version 7 oder neuer), und ein Administratorkonto, um den Bot anzulegen.
  • Ein Bot-Konto (oder ein eigener Benutzer mit einem persönlichen Zugriffstoken). Nimm nicht dein persönliches Konto: Der Bot antwortet in seinem Namen.
  • Der Benutzername jeder Person, die mit dem Bot sprechen darf, zum Beispiel alice.

Einrichtung​

  1. In Mattermost, Systemkonsole → Integrationen → Bot-Konten: Schalte Erstellen von Bot-Konten aktivieren ein.
  2. Hauptmenü Integrationen → Bot-Konten → Bot-Konto hinzufügen: ein Benutzername wie gladys, die Rolle Mitglied. Kopiere das Token, das am Ende nur einmal angezeigt wird.
  3. Füge den Bot deinem Team hinzu (Teammenü Mitglieder hinzufügen, oder Systemkonsole → Benutzer).
  4. In Gladys, Integrationen → Mattermost → Konfiguration:
    • Serveradresse: die Adresse von Mattermost wie im Browser, zum Beispiel https://chat.example.org oder http://192.168.1.20:8065.
    • Token des Bots: das Token aus Schritt 2.
    • Erlaubte Personen: die Benutzernamen, auf die der Bot hört, durch Kommas getrennt (alice, bob). Leer antwortet der Bot niemandem: Er ignoriert die Nachrichten aller, die nicht in dieser Liste stehen.
    • Beobachtete Kanäle: die Kanäle, deren Nachrichten Szenen starten, geschrieben als Team/Kanal wie in ihrer Adresse (https://chat.example.org/zuhause/channels/garage ergibt zuhause/garage; die ganze Adresse geht auch), oder per Kanal-ID, durch Kommas getrennt. Der Bot tritt öffentlichen Kanälen selbst bei; füge ihn vorher privaten Kanälen hinzu.
    • Befehlspräfix: standardmäßig ! (/ gehört den Slash-Befehlen von Mattermost).
    • Sprache des Bots: die Sprache dessen, was der Bot schreibt, bevor eine Person verknüpft ist.
  5. Klicke auf Verbindung testen: Der Bericht nennt das Konto des Bots, die beobachteten Kanäle, denen er beigetreten ist, und die gefundenen erlaubten Personen. Der Verbindungsstatus der Seite sagt es auch und nennt einen Kanal oder eine Person, die nicht gefunden wurde.

Dein Mattermost-Konto verknüpfen, um mit Gladys zu sprechen​

Jeder Gladys-Benutzer, der aus Mattermost mit Gladys sprechen will, macht das einmal:

  1. In Gladys, Integrationen → Mattermost → Konfiguration, Block „Mein Konto verknüpfen“: Klicke auf Verknüpfungscode generieren.
  2. Öffne in Mattermost eine Direktnachricht mit dem Bot (das + neben „Direktnachrichten“, dann sein Benutzername) und schick ihm den Code (8 Zeichen). Der Bot bestätigt: Dein Mattermost-Konto ist mit deinem Gladys-Benutzer verknüpft. Im selben Block kannst du die Verknüpfung wieder lösen.

Was der Bot macht​

  • In einer Direktnachricht mit einer erlaubten Person: Er gibt die Nachrichten an Gladys weiter, mit den Rechten des verknüpften Gladys-Benutzers, genau wie der Telegram-Bot: „Wie warm ist es im Wohnzimmer?“, „Mach das Licht aus“. Die Antworten von Gladys kommen in dieser Direktnachricht zurück, Markdown von Mattermost dargestellt. Die Nachrichten, die Gladys dir schickt (die Szenenaktion Nachricht senden, die Systemnachrichten), kommen auch dort an, sogar vor jedem Gespräch. Ein Kamerabild aus einer Szene kommt als Bild an.
  • In einem beobachteten Kanal: Jede Nachricht einer erlaubten Person startet den Auslöser Mattermost-Nachricht empfangen, und eine Nachricht, die mit dem Präfix beginnt, startet auch Mattermost-Befehl empfangen. Der Bot antwortet dort nie von selbst: Was passiert, entscheiden deine Szenen.
  • In jedem anderen Kanal (eine Gruppennachricht, ein nicht beobachteter Kanal): Er schweigt. Gladys antwortet nie dort, wo andere mitlesen.
  • Was er ignoriert: alle, die keine erlaubte Person sind, seine eigenen Nachrichten (eine Szene, die in einen beobachteten Kanal schreibt, startet sich nie selbst neu), Systemnachrichten („ist dem Kanal beigetreten“), Bearbeitungen und Nachrichten, die beim Lesen älter als 5 Minuten sind (ein „!garage auf“ von vor zwei Stunden läuft jetzt nicht).
  • Nach einer Unterbrechung (Neustart des Servers, von Gladys, kurzer Netzausfall): Er verbindet sich selbst neu und liest die Nachrichten der beobachteten Kanäle und der Direktnachrichten der letzten 5 Minuten nach.

Dashboard​

Das Widget Mattermost zeigt, ob der Bot verbunden ist, sein Konto, die beobachteten Kanäle, in denen er ist, die letzten 5 Nachrichten aus den beobachteten Kanälen (Autor, Text, Datum) und eine Schaltfläche Verbindung testen. Die Direktnachrichten mit Gladys erscheinen nie: Alle, die das Dashboard sehen, sehen das Widget.

Szenen​

Auslöser​

  • Mattermost-Nachricht empfangen: Eine erlaubte Person hat in einem beobachteten Kanal geschrieben. Filter (leer = alle): Kanal (wie in der Konfiguration geschrieben, zum Beispiel zuhause/garage) und Absender (der Benutzername ohne @: alice). Variablen: Nachricht, Absender, Kanal, Kanal-ID.
  • Mattermost-Befehl empfangen: Eine erlaubte Person hat einen Befehl in einem beobachteten Kanal geschrieben: das Präfix, dann ein Wort, dann optionale Argumente, zum Beispiel !licht aus kueche. Filter Befehl: das Wort ohne Präfix, kleingeschrieben (licht); dazu Kanal, Absender. Variablen: Befehl (licht), Argumente (aus kueche), Nachricht, Absender, Kanal, Kanal-ID. Dieselbe Nachricht startet auch Mattermost-Nachricht empfangen.
  • Mattermost-Verbindung verloren: Der Bot erreicht den Server nicht mehr, seit einer Minute, oder sein Token wird abgelehnt. Variable: Fehler. Einmal gestartet, bis die Verbindung zurück ist.
  • Mattermost-Verbindung wiederhergestellt: Der Bot erreicht den Server nach einem Verbindungsverlust wieder. Variable: Bot-Konto (Benutzername).

Aktionen​

  • Mattermost-Nachricht senden: schreibt eine Nachricht in einen Kanal (Team/Kanal, seine Adresse oder seine ID) oder als Direktnachricht an eine Person (@alice). Die Nachricht akzeptiert Szenenvariablen und das Markdown von Mattermost (**fett**, _kursiv_, Listen, Links, @here). Der Bot muss im Kanal sein oder ihm beitreten können (ein öffentlicher Kanal seines Teams). Ergebnisse: Gesendet (ja/nein), Beitrags-ID, Fehler. Eine fehlgeschlagene Nachricht hält die Szene nicht an: Prüfe Gesendet bei Bedarf mit einer Bedingung.

Um einem Gladys-Benutzer zu schreiben, geht auch die Aktion Nachricht senden von Gladys: Damit erreichst du sein verknüpftes Mattermost-Konto.

Szenenideen​

  • Garage per Befehl: Auslöser Mattermost-Befehl empfangen, Befehl garage, Kanal zuhause/garage; dann eine Bedingung auf die Variable Argumente gleich zu und die Aktion, die die Garage schließt.
  • Waschmaschine fertig: Wenn die Leistung der Steckdose der Waschmaschine sinkt, Mattermost-Nachricht senden an zuhause/familie: „Die Waschmaschine ist fertig @here“.
  • Warnung, wenn der Bot getrennt ist: Auslöser Mattermost-Verbindung verloren, dann eine Benachrichtigung über einen anderen Kanal (Gotify, ntfy, SMS) mit der Variable Fehler.

Fehlerbehebung​

  • „kein Mattermost-Server unter dieser Adresse“: Nimm die Adresse, mit der du Mattermost im Browser öffnest, ohne /login und ohne Team. https://<adresse>/api/v4/system/ping muss {"status":"OK"…} antworten.
  • „Zugriffstoken abgelehnt“: Das Token wurde widerrufen oder das Bot-Konto deaktiviert. Erstelle ein neues Token unter Integrationen → Bot-Konten.
  • Einem beobachteten Kanal wurde nicht beigetreten: Der Status der Seite und der Test nennen ihn. Prüfe die Namen von Team und Kanal in der Adresse des Kanals, füge den Bot dem Team hinzu und dem Kanal, wenn er privat ist, und speichere die Konfiguration erneut.
  • Der Bot antwortet mir nicht: Steht dein Benutzername genau so in Erlaubte Personen? Schreibst du ihm eine Direktnachricht (keine Gruppennachricht)? Ist dein Konto verknüpft (sonst erklärt dir der Bot, wie es geht)?
  • Ein Befehl startet die Szene nicht: Der Filter Befehl ist das Wort ohne Präfix, kleingeschrieben: licht, nicht !Licht.
  • Hinter einem Reverse-Proxy muss auch der WebSocket (/api/v4/websocket) weitergeleitet werden, wie für die Mattermost-Apps.
  • Mehr Details in den Protokollen der Integration mit LOG_LEVEL=debug.

Einschränkungen​

  • Eine mit Gladys verknüpfte Person kann aus Mattermost alles tun, was ihr Gladys-Benutzer darf: Halte die Liste der erlaubten Personen kurz und das Token des Bots geheim.
  • Ein Bot-Konto pro Gladys. Der Bot liest die Nachrichten über den WebSocket von Mattermost: Ein Befehl wirkt in etwa einer Sekunde. Nachrichten, die während einer Unterbrechung von mehr als 5 Minuten geschrieben wurden, werden übersprungen.
  • Dateien, Bilder und Sprachnachrichten an den Bot werden ignoriert; nur Text zählt. Threads werden wie normale Nachrichten gelesen, und die Antworten von Gladys landen nicht im Thread.
  • Der Bot unterliegt den API-Ratenlimits des Servers (standardmäßig 10 Anfragen pro Sekunde und Konto): Halte die Nachrichten deiner Szenen in vernünftigem Rahmen.
  • Nicht mit Mattermost, Inc. verbunden. Mattermost ist eine Marke von Mattermost, Inc.

Konfigurationseinstellungen​

Diese Einstellungen fragt Mattermost in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Erste SchrittesectionNeinLeg in Mattermost ein Bot-Konto an (Systemkonsole → Integrationen → Bot-Konten), füge es deinem Team hinzu und kopiere sein Token. Schreib ihm dann eine Direktnachricht.
ServeradressestringJaDie Adresse deines Mattermost, wie im Browser, z. B. https://chat.example.org oder http://192.168.1.20:8065.
Token des BotssecretNeinDas Zugriffstoken des Bot-Kontos (oder ein persönliches Zugriffstoken eines eigenen Kontos).
Erlaubte PersonenstringNeinBenutzernamen, auf die der Bot hört, durch Kommas getrennt, z. B. alice, bob. Leer: Der Bot antwortet niemandem.
Beobachtete KanälestringNeinKanäle, deren Nachrichten Szenen auslösen, als Team/Kanal (wie in ihrer Adresse) oder per ID, durch Kommas getrennt. Der Bot tritt öffentlichen Kanälen bei; füge ihn privaten Kanälen hinzu.
BefehlspräfixstringNeinEine Nachricht, die damit beginnt, ist ein Befehl, z. B. !licht aus. Ein bis drei Zeichen.
Sprache des BotsselectNeinSprache dessen, was der Bot schreibt, bevor eine Person verknüpft ist, und der Berichte.

So installierst du Mattermost in Gladys​

  1. Öffne in Gladys Integrationen: Mattermost erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-mattermost:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-mattermost.

Mattermost benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

Mattermost ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂
Zuletzt aktualisiert am