Zum Hauptinhalt springen

Rocket.Chat Smart-Home-Integration, kostenlos und Open Source

Rocket.Chat-Integration für Gladys Assistant

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

Auf GitHub ansehenAlle Integrationen

Sprich mit Gladys über Rocket.Chat, 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 Rocket.Chat-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 Rocket.Chat-Servers, im lokalen Netz oder im Internet.

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

Voraussetzungen​

  • Gladys Assistant 5.1.0 oder neuer.
  • Ein Rocket.Chat-Server, den Gladys erreicht (getestet mit 8.9; Bilder senden braucht 6.8 oder neuer), und ein Administratorkonto, um den Bot anzulegen.
  • Ein Benutzer für den Bot 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 Rocket.Chat, Administration → Benutzer → Neuer Benutzer: ein Benutzername wie gladys, eine E-Mail-Adresse und ein Passwort, die Rollen bot und user.
  2. Melde dich mit diesem Benutzer bei Rocket.Chat an, Profil → Persönliche Zugangsschlüssel: Gib einen Namen ein, aktiviere Zwei-Faktor-Authentifizierung ignorieren, klicke auf Hinzufügen. Kopiere das Token und die Benutzer-ID, die nur einmal angezeigt werden.
  3. In Gladys, Integrationen → Rocket.Chat → Konfiguration:
    • Serveradresse: die Adresse von Rocket.Chat wie im Browser, zum Beispiel https://chat.example.org oder http://192.168.1.20:3000.
    • Benutzer-ID des Bots und Persönliches Zugriffstoken: die beiden Werte aus Schritt 2.
    • Erlaubte Personen: die Benutzernamen, auf die der Bot hört, durch Kommas getrennt (alice, bob), genau wie in Rocket.Chat geschrieben: Groß- und Kleinschreibung zählt. 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 #name (die Adresse https://chat.example.org/channel/garage oder die ID des Kanals gehen auch), 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 Rocket.Chat).
    • Sprache des Bots: die Sprache dessen, was der Bot schreibt, bevor eine Person verknüpft ist.
  4. 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 Rocket.Chat-Konto verknüpfen, um mit Gladys zu sprechen​

Jeder Gladys-Benutzer, der aus Rocket.Chat mit Gladys sprechen will, macht das einmal:

  1. In Gladys, Integrationen → Rocket.Chat → Konfiguration, Block „Mein Konto verknüpfen“: Klicke auf Verknüpfungscode generieren.
  2. Öffne in Rocket.Chat eine Direktnachricht mit dem Bot (das Stiftsymbol Neu erstellen → Direktnachricht, dann sein Benutzername) und schick ihm den Code (8 Zeichen). Der Bot bestätigt: Dein Rocket.Chat-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 Rocket.Chat 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 Rocket.Chat-Nachricht empfangen, und eine Nachricht, die mit dem Präfix beginnt, startet auch Rocket.Chat-Befehl empfangen. Der Bot antwortet dort nie von selbst: Was passiert, entscheiden deine Szenen.
  • In jedem anderen Raum (ein nicht beobachteter Kanal, eine Direktnachricht mit mehreren Personen): 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), Nachrichten von eingehenden Webhooks und Apps (auch wenn sie im Namen einer erlaubten Person schreiben), 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 Rocket.Chat 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​

  • Rocket.Chat-Nachricht empfangen: Eine erlaubte Person hat in einem beobachteten Kanal geschrieben. Filter (leer = alle): Kanal (wie in der Konfiguration geschrieben, zum Beispiel #garage) und Absender (der Benutzername ohne @: alice). Variablen: Nachricht, Absender, Kanal, Kanal-ID.
  • Rocket.Chat-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 Rocket.Chat-Nachricht empfangen.
  • Rocket.Chat-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.
  • Rocket.Chat-Verbindung wiederhergestellt: Der Bot erreicht den Server nach einem Verbindungsverlust wieder. Variable: Bot-Konto (Benutzername).

Aktionen​

  • Rocket.Chat-Nachricht senden: schreibt eine Nachricht in einen Kanal (#name, seine Adresse oder seine ID) oder als Direktnachricht an eine Person (@alice). Die Nachricht akzeptiert Szenenvariablen und das Markdown von Rocket.Chat (**fett**, _kursiv_, Listen, Links, @here). Ein öffentlicher Kanal nimmt die Nachricht an, auch wenn der Bot nicht darin ist; ein privater nur, wenn er Mitglied ist. Ergebnisse: Gesendet (ja/nein), Nachrichten-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 Rocket.Chat-Konto.

Szenenideen​

  • Garage per Befehl: Auslöser Rocket.Chat-Befehl empfangen, Befehl garage, Kanal #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, Rocket.Chat-Nachricht senden an #familie: „Die Waschmaschine ist fertig @here“.
  • Warnung, wenn der Bot getrennt ist: Auslöser Rocket.Chat-Verbindung verloren, dann eine Benachrichtigung über einen anderen Kanal (Gotify, ntfy, SMS) mit der Variable Fehler.

Fehlerbehebung​

  • „kein Rocket.Chat-Server unter dieser Adresse“: Nimm die Adresse, mit der du Rocket.Chat im Browser öffnest, ohne /home und ohne Kanal. https://<adresse>/api/info muss {"version":…,"success":true} antworten.
  • „Benutzer-ID oder Zugriffstoken abgelehnt“: Das Token wurde gelöscht, die Benutzer-ID gehört nicht zum Token, oder das Bot-Konto wurde deaktiviert. Erstelle ein neues Token unter Profil → Persönliche Zugangsschlüssel.
  • Einem beobachteten Kanal wurde nicht beigetreten: Der Status der Seite und der Test nennen ihn. Prüfe den Namen des Kanals, füge den Bot hinzu, wenn er privat ist, und speichere die Konfiguration erneut.
  • Der Bot antwortet mir nicht: Steht dein Benutzername genau so, mit derselben Groß- und Kleinschreibung, in Erlaubte Personen? Schreibst du ihm eine Direktnachricht, mit ihm allein? 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 (/websocket) weitergeleitet werden, wie für die Rocket.Chat-Apps.
  • Mehr Details in den Protokollen der Integration mit LOG_LEVEL=debug.

Einschränkungen​

  • Eine mit Gladys verknüpfte Person kann aus Rocket.Chat 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 die Echtzeit-API von Rocket.Chat (DDP über den WebSocket): 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.
  • Eine Nachricht hat standardmäßig höchstens 5000 Zeichen (Einstellung Nachricht → Maximal erlaubte Nachrichtengröße): Eine längere Antwort von Gladys wird gekürzt. Die Rolle bot ist von den API-Ratenlimits des Servers ausgenommen.
  • Nicht mit Rocket.Chat Technologies Corp. verbunden. Rocket.Chat ist eine Marke von Rocket.Chat Technologies Corp.

Konfigurationseinstellungen​

Diese Einstellungen fragt Rocket.Chat in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Erste SchrittesectionNeinLeg in Rocket.Chat einen Benutzer für den Bot an (Administration → Benutzer, Rolle bot), melde dich damit an, erstelle ein persönliches Zugriffstoken (Profil → Persönliche Zugangsschlüssel) und kopiere Token und Benutzer-ID. Schreib ihm dann eine Direktnachricht.
ServeradressestringJaDie Adresse deines Rocket.Chat, wie im Browser, z. B. https://chat.example.org oder http://192.168.1.20:3000.
Benutzer-ID des BotsstringJaWird beim Erstellen neben dem Token angezeigt (17 oder 24 Zeichen).
Persönliches ZugriffstokensecretNeinDas persönliche Zugriffstoken des Bot-Kontos (aktiviere beim Erstellen „Zwei-Faktor-Authentifizierung ignorieren“).
Erlaubte PersonenstringNeinBenutzernamen, auf die der Bot hört, durch Kommas getrennt, genau wie in Rocket.Chat (Groß- und Kleinschreibung zählt), z. B. alice, bob. Leer: Der Bot antwortet niemandem.
Beobachtete KanälestringNeinKanäle, deren Nachrichten Szenen auslösen, als #name, per 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 Rocket.Chat in Gladys​

  1. Öffne in Gladys Integrationen: Rocket.Chat 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-rocketchat:1.0.0) 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-rocketchat.

Rocket.Chat 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​

Rocket.Chat 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