- /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>
100 lines
5.7 KiB
Markdown
100 lines
5.7 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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`.
|