inhaus-plugin-chat/README.md
Friederich Loheide 5f71c3e250 Nachrichten 1.1.0: Schnittstelle für die App, Verbindung prüfen
- /api/v1/chat: config, Gruppenchats, verlassen, bearbeiten, löschen, Reaktionen,
  „Gibt es Neues?“, „schreibt …“, GIFs, Echtzeit-Anmeldung und Anhänge mit Token
- Anhang-Adressen zeigen bei API-Aufrufen auf die API (Token statt Sitzung)
- Backend: „Echtzeit prüfen“ und „GIPHY prüfen“ melden sofort, ob die Zugangsdaten stimmen
- README: Schritt-für-Schritt-Einrichtung für pusher.com und GIPHY

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 20:10:35 +00:00

5.7 KiB
Raw Blame History

Nachrichten – Chat-Plugin für Inhaus

Direktnachrichten und Gruppenchats im Mitarbeiterportal.

  • Direktnachrichten an alle Kolleginnen und Kollegen (Personensuche), Gruppenchats für alle mit dem Recht „Gruppenchats anlegen“ (unter Rollen vergeben). Gruppen-Admins benennen um, fügen hinzu, entfernen, ernennen Admins.
  • Anhänge (Bilder, PDFs, Office …; Einfügen aus der Zwischenablage, Ziehen & Ablegen), GIFs, Emojis, Reaktionen, Antworten auf einzelne Nachrichten, Bearbeiten und Löschen eigener Nachrichten.
  • Ungelesen-Zähler als Sprechblase neben der Glocke, „Neu“-Trenner, „gelesen“ unter eigenen Nachrichten, „schreibt gerade …“. Stummschalten je Gespräch.
  • Benachrichtigung (Glocke und Push, auch in der Inhaus-App) – je Gespräch einmal, bis es gelesen ist, und nicht, während das Gespräch offen ist.
  • Handy- und Desktop-Ansicht, Tastatur (Enter sendet, Umschalt+Enter neue Zeile, Esc bricht ab), Screenreader-Hinweise.

Voraussetzung: Inhaus 0.39.0 oder neuer.

Installation

  1. Neuestes Release herunterladen: chat-<version>.zip unter https://git.loheide.cloud/friloo/inhaus-plugin-chat/releases
  2. Backend → Plugins → hochladen → aktivieren. Updates erscheinen danach automatisch unter „Plugins“.
  3. Unter Rollen das Recht „Gruppenchats anlegen“ an die passenden Rollen vergeben (z. B. Teamleitungen).
  4. Optional unter Portal → Nachrichten: GIPHY, Echtzeit, Größe von Anhängen; unter Portal → Chat-GIFs die eigene GIF-Sammlung (Recht „Nachrichten einrichten“).

Datenschutz

  • Gespräche sehen nur ihre Mitglieder – auch die Administration kann nicht mitlesen. Anhänge liegen außerhalb des öffentlichen Ordners und werden nur an Mitglieder ausgeliefert.
  • GIPHY ist aus, bis ein Schlüssel eingetragen ist. Dann gehen Suchbegriffe an GIPHY und die Bilder werden von dort geladen. Die eigene Sammlung bleibt im Haus.
  • Echtzeit: Über den Dienst geht nur das Signal „es gibt Neues“ – keine Inhalte.
  • Beim Entfernen des Plugins mit „Daten löschen“ verschwinden alle Nachrichten und Anhänge.

Echtzeit (optional)

Ohne Einrichtung fragt der Chat alle 3 Sekunden (im Hintergrund seltener) nach Neuem – das läuft auf jedem Webspace. Für sofortige Zustellung braucht es einen Pusher-kompatiblen Dienst. Über ihn geht nur das Signal „es gibt Neues“, nie Nachrichteninhalte. Auf einem reinen Webspace (ohne dauerhaft laufende Prozesse) ist pusher.com der einfachste Weg:

  1. Kostenloses Konto unter https://dashboard.pusher.com anlegen („Channels“, Sandbox-Tarif: 200 000 Signale/Tag, 100 gleichzeitige Verbindungen – für die meisten Häuser genug).
  2. „Create app“: Name z. B. „Inhaus“, Cluster eu (Server in der EU), Frontend „Vanilla JS“, Backend „Laravel“.
  3. Unter „App Keys“ stehen app_id, key, secret und cluster.
  4. Im Backend unter Portal → Nachrichten → Echtzeit einschalten, App-ID, Key, Secret und Cluster (eu) eintragen, Server leer lassen, speichern.
  5. Oben auf „Echtzeit prüfen“ klicken – „Verbindung steht“ heißt: fertig.

Alternativ ein eigener Server mit Laravel Reverb oder Soketi: App-ID, Key, Secret, Server (z. B. ws.example.org) und Port (443) eintragen. Der Server muss vom Browser bzw. der App (WebSocket) und vom Portal (HTTP) aus erreichbar sein. Die Inhaus-App nutzt dieselbe Einrichtung automatisch.

GIPHY (optional)

Die eigene GIF-Sammlung (Backend → Chat-GIFs) funktioniert ohne Einrichtung. Für die Suche bei GIPHY:

  1. Unter https://developers.giphy.com/dashboard/ anmelden, „Create an App“ → API (nicht SDK) wählen.
  2. Den angezeigten API-Key im Backend unter Portal → Nachrichten → GIFs eintragen und speichern.
  3. Oben auf „GIPHY prüfen“ klicken.

Ein neuer Schlüssel ist ein Beta-Schlüssel (100 Abrufe pro Stunde); für mehr bei GIPHY ein „Production“-Upgrade beantragen. Suchbegriffe gehen dabei an GIPHY, die GIFs lädt der Browser von dort.

Schnittstelle für die App

Unter /api/v1/chat/… (Token nötig), dieselben Regeln wie im Portal:

Methode Pfad Zweck
GET config eigene Person, can_create_groups, giphy, realtime (ohne Secret), reactions, max_upload_mb
GET conversations Gesprächsliste
POST direct {user_id} / groups {name, members[]} Direktnachricht öffnen / Gruppenchat anlegen (Recht nötig)
DELETE conversations/{id} Gespräch verlassen
GET conversations/{id}/messages?vor= 40 Nachrichten, ältere mit vor
POST conversations/{id}/messages {body, gif_url, reply_to, files[]} senden (JSON oder multipart)
POST conversations/{id}/read {message_id} / typing gelesen / „schreibt …“
PUT / DELETE messages/{id} bearbeiten / löschen
POST messages/{id}/reaction {emoji} Reaktion umschalten
GET updates?seit=&offen=&nach= „Gibt es Neues?“ – wie im Portal
GET unread, gifs?q= ungelesene Nachrichten, GIF-Suche
POST realtime/auth {socket_id, channel_name} Anmeldung am privaten Echtzeit-Kanal
GET attachments/{id} Anhang (Adressen in den Antworten zeigen bei API-Aufrufen hierher)

Entwicklung

npm install
npm run build        # dist/ – wird mit ins Repository eingecheckt
npm run package      # baut und erzeugt chat-<version>.zip

Tests laufen in einer Inhaus-Installation, in der das Plugin unter plugins/chat liegt (Kopie oder Symlink):

vendor-dev/bin/phpunit plugins/chat/tests

Release: Version in plugin.json erhöhen, npm run package, Tag vX.Y.Z setzen und tea release create --tag vX.Y.Z --asset chat-X.Y.Z.zip.