Zum Hauptinhalt springen

Zulip Smart-Home-Integration, kostenlos und Open Source

Zulip-Integration für Gladys Assistant

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

Auf GitHub ansehenAlle Integrationen

Sprich mit Gladys über Zulip, den freien Team-Chat mit Kanälen und Themen, so wie mit dem Telegram-Bot von Gladys: Stell eine Frage, starte eine Szene, erhalte die Nachrichten von Gladys als Direktnachricht. Die Integration schreibt außerdem aus deinen Szenen in Zulip-Kanäle und startet Szenen, wenn in einem beobachteten Kanal eine Nachricht oder ein Befehl wie !licht aus geschrieben wird. Die Integration nutzt einen generischen Bot deiner Zulip-Organisation: einen Server, den du im lokalen Netz betreibst, oder Zulip Cloud.

Ohne die Hardware entwickelt: Rückmeldungen willkommen. Die Integration wurde gegen einen echten Zulip-Server getestet (12.3, in Docker), aber nicht in einem echten Gladys und nicht mit allen Zulip-Apps. Sag uns, was funktioniert und was nicht, in den Issues oder im Gladys-Forum.

Voraussetzungen​

  • Gladys Assistant 5.1.0 oder neuer.
  • Eine Zulip-Organisation, die Gladys erreichen kann: ein selbst betriebener Server (Version 7 oder neuer) oder Zulip Cloud (der kostenlose Tarif genügt).
  • Ein generischer Bot dieser Organisation (kein Bot für eingehende oder ausgehende Webhooks). Nimm nicht dein persönliches Konto: Der Bot antwortet in seinem Namen.
  • Die E-Mail oder die Benutzer-ID jeder Person, die mit dem Bot sprechen darf.

Einrichtung​

  1. In Zulip Persönliche Einstellungen → Bots → Neuen Bot hinzufügen: Typ Generischer Bot, ein Name wie Gladys, eine Bot-E-Mail wie gladys-bot. Zulip gibt ihm eine E-Mail wie [email protected].
  2. Kopiere auf der Karte des Bots seine E-Mail und seinen API-Schlüssel (das Schlüsselsymbol oder zuliprc herunterladen).
  3. In Gladys Integrationen → Zulip → Konfiguration:
    • Adresse der Organisation: die Adresse deiner Organisation wie im Browser, zum Beispiel https://example.zulipchat.com oder http://192.168.1.20.
    • E-Mail des Bots und API-Schlüssel: die aus Schritt 2.
    • Erlaubte Personen: die Personen, auf die der Bot hört, durch Kommas getrennt, per E-Mail wie in Zulip angezeigt oder per Benutzer-ID ([email protected], 12). Leer antwortet der Bot niemandem: Er ignoriert die Nachrichten aller, die nicht in dieser Liste stehen. Viele Organisationen verbergen die E-Mails vor Bots: Nimm dann die Benutzer-ID, die im Profil der Person steht (auf ihren Namen klicken, dann Profil anzeigen). Die Logs der Integration nennen auch die Benutzer-ID einer noch nicht erlaubten Person, wenn sie dem Bot schreibt.
    • Beobachtete Kanäle: die Kanäle, deren Nachrichten Szenen starten, nach Name (garage, #Wohnzimmer), durch Kommas getrennt. Der Bot abonniert öffentliche Kanäle selbst; abonniere ihn zuerst für private Kanäle. Ein Name, den es nicht gibt, wird gemeldet, nie angelegt.
    • Befehlspräfix: standardmäßig ! (/ öffnet die Befehle von Zulip).
    • Sprache des Bots: die Sprache dessen, was der Bot schreibt, bevor eine Person verknüpft ist.
  4. Klicke auf Verbindung testen: Der Bericht nennt die E-Mail des Bots, die gefundenen beobachteten Kanäle und die gefundenen erlaubten Personen. Der Verbindungsstatus der Seite sagt es auch und nennt einen Kanal oder eine Person, die nicht gefunden wurde.

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

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

  1. In Gladys, Integrationen → Zulip → Konfiguration, Block „Mein Konto verknüpfen“: Klicke auf Verknüpfungscode generieren.
  2. Öffne in Zulip eine Direktnachricht mit dem Bot (das + neben „Direktnachrichten“, dann sein Name) und schick ihm den Code (8 Zeichen). Der Bot bestätigt: Dein Zulip-Konto ist mit deinem Gladys-Benutzer verknüpft. Du kannst die Verknüpfung im selben Block 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 diese Direktnachricht zurück, mit dem Markdown von Zulip dargestellt. Die Nachrichten, die Gladys dir schickt (die Szenenaktion Nachricht senden, die Systemnachrichten), kommen auch dort an, sogar vor jedem Gespräch. Ein Kamerabild einer Szene kommt als Bild an.
  • In einem beobachteten Kanal: Jede Nachricht einer erlaubten Person, in jedem Thema, startet den Auslöser Zulip-Nachricht empfangen, und eine Nachricht, die mit dem Präfix beginnt, startet zusätzlich Zulip-Befehl empfangen. Eine Erwähnung des Bots am Anfang wird entfernt: @**Gladys** !licht aus ist der Befehl licht. Der Bot antwortet dort nie von selbst: Was passiert, bestimmen deine Szenen.
  • Überall sonst (eine Gruppen-Direktnachricht, ein nicht beobachteter Kanal): Er schweigt. Gladys antwortet nie dort, wo andere mitlesen.
  • Was er ignoriert: alle, die keine erlaubten Personen sind, alle Bots (auch seine eigenen Nachrichten: Eine Szene, die in einen beobachteten Kanal schreibt, startet sich nie selbst wieder), Bearbeitungen und Nachrichten, die beim Lesen älter als 5 Minuten sind (ein „!garage auf“ von vor zwei Stunden läuft jetzt nicht mehr).
  • Nach einer Unterbrechung (Neustart des Servers, von Gladys, Netzwerk): Er verbindet sich selbst wieder. Zulip hebt die Nachrichten einer Unterbrechung unter 10 Minuten für den Bot auf; nach einer längeren oder einem Neustart liest der Bot die Nachrichten der letzten 5 Minuten nach.

Dashboard​

Das Widget Zulip zeigt, ob der Bot verbunden ist, seine E-Mail, die Zahl der beobachteten Kanäle, die letzten 5 Nachrichten aus den beobachteten Kanälen (Absender, Thema, 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​

  • Zulip-Nachricht empfangen: Eine erlaubte Person hat in einen beobachteten Kanal geschrieben. Filter (leer = alle): Kanal (wie in der Konfiguration, zum Beispiel garage), Thema (tor) und Absender (wie bei den erlaubten Personen: [email protected] oder 12). Variablen: Nachricht, Absender, Name des Absenders, Kanal, Thema, Kanal-ID.
  • Zulip-Befehl empfangen: Eine erlaubte Person hat einen Befehl in einen 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, Thema, Absender. Variablen: Befehl (licht), Argumente (aus kueche), Nachricht, Absender, Name des Absenders, Kanal, Thema, Kanal-ID. Dieselbe Nachricht startet auch Zulip-Nachricht empfangen.
  • Zulip-Verbindung verloren: Der Bot erreicht den Server nicht mehr, seit einer Minute, oder sein Schlüssel wird abgelehnt. Variable: Fehler. Einmal gestartet, bis die Verbindung zurück ist.
  • Zulip-Verbindung wiederhergestellt: Der Bot erreicht den Server wieder nach einem Verbindungsverlust. Variable: Bot-Konto (E-Mail).

Aktionen​

  • Zulip-Nachricht senden: schreibt eine Nachricht in einen Kanal (sein Name, garage oder #garage) unter einem Thema (Gladys, wenn leer) oder an eine Person als Direktnachricht (ihre E-Mail, oder @ und ihre Benutzer-ID: @12). Die Nachricht akzeptiert Szenenvariablen und das Markdown von Zulip (**fett**, *kursiv*, Listen, Links, @**all**). Der Bot muss einen öffentlichen Kanal nicht abonniert haben. 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 Zulip-Konto.

Szenenideen​

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

Fehlerbehebung​

  • „kein Zulip-Server unter dieser Adresse“: Nimm die Adresse, mit der du Zulip im Browser öffnest, ohne /login und ohne das, was nach # kommt. https://<adresse>/api/v1/server_settings muss {"result":"success"…} antworten.
  • „E-Mail oder API-Schlüssel des Bots abgelehnt“: Der Schlüssel wurde neu erzeugt, der Bot deaktiviert, oder die E-Mail ist nicht die des Bots (…-bot@…). Kopiere sie erneut aus Persönliche Einstellungen → Bots.
  • Ein beobachteter Kanal wird nicht gefunden: Der Status der Seite und der Test nennen ihn. Prüfe den Namen; abonniere den Bot zuerst für einen privaten Kanal und speichere dann die Konfiguration erneut.
  • Eine Person wird nicht gefunden: Die E-Mails sind in deiner Organisation wohl vor Bots verborgen: Nimm die Benutzer-ID. Bots und deaktivierte Konten sind nie erlaubt.
  • Der Bot antwortet mir nicht: Stehst du in Erlaubte Personen? Schreibst du ihm eine Direktnachricht, nur ihr beide (keine Gruppen-Direktnachricht)? Ist dein Konto verknüpft (der Bot gibt dir dann die Anleitung)?
  • Ein Befehl startet die Szene nicht: Der Filter Befehl ist das Wort ohne Präfix, kleingeschrieben: licht, nicht !Licht.
  • Mehr Details in den Logs der Integration mit LOG_LEVEL=debug.

Einschränkungen​

  • Eine mit Gladys verknüpfte Person kann von Zulip aus alles tun, was ihr Gladys-Benutzer darf: Halte die Liste der erlaubten Personen kurz und den API-Schlüssel des Bots geheim.
  • Ein Bot pro Gladys. Der Bot liest die Nachrichten über die Ereigniswarteschlange von Zulip (Long Polling): Ein Befehl wirkt nach etwa einer Sekunde. Nachrichten, die während einer Unterbrechung von mehr als 5 Minuten verpasst wurden, werden übersprungen.
  • Dateien, Bilder und Sprachnachrichten an den Bot kommen als Markdown-Link an; nur der Text zählt. Die Antworten von Gladys gehen in die Direktnachricht, nie in einen Kanal.
  • Zulip begrenzt jedes Konto standardmäßig auf 200 Anfragen pro Minute: Halte die Nachrichten deiner Szenen vernünftig.
  • Nicht mit Kandra Labs, Inc. verbunden. Zulip ist eine Marke von Kandra Labs, Inc.

Konfigurationseinstellungen​

Diese Einstellungen fragt Zulip in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Erste SchrittesectionNeinLeg in Zulip einen generischen Bot an (Persönliche Einstellungen → Bots → Neuen Bot hinzufügen) und kopiere seine E-Mail und seinen API-Schlüssel. Schreib ihm dann eine Direktnachricht.
Adresse der OrganisationstringJaDie Adresse deiner Zulip-Organisation wie im Browser, z. B. https://example.zulipchat.com oder http://192.168.1.20.
E-Mail des BotsstringJaDie E-Mail des Bots, angezeigt unter Persönliche Einstellungen → Bots, z. B. [email protected].
API-SchlüsselsecretNeinDer API-Schlüssel des Bots (Persönliche Einstellungen → Bots). Ein generischer Bot, kein eingehender Webhook.
Erlaubte PersonenstringNeinE-Mails (wie in Zulip angezeigt) oder Benutzer-IDs der Personen, auf die der Bot hört, durch Kommas getrennt. Leer: Der Bot antwortet niemandem.
Beobachtete KanälestringNeinKanäle, deren Nachrichten Szenen auslösen, nach Name, durch Kommas getrennt. Der Bot tritt öffentlichen Kanälen bei; abonniere ihn für private.
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 Zulip in Gladys​

  1. Öffne in Gladys Integrationen: Zulip 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-zulip: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-zulip.

Zulip 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​

Zulip 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