Hermes Agent
222 lines
12 KiB
Markdown
222 lines
12 KiB
Markdown
# Multi-Channel-Erweiterung für Boardgame.network — Analyse & Implementierungsplan
|
||
|
||
> **Für:** Daniel Krause (brettspiel-news.de)
|
||
> **Datum:** 18.06.2026
|
||
> **Status:** Analyse & Priorisierung
|
||
|
||
---
|
||
|
||
## Ist-Zustand
|
||
|
||
Das aktuelle Intake-System (`app.py` auf Port 5002) unterstützt:
|
||
|
||
| Kanal | Status | Einträge in DB | Technik |
|
||
|---|---|---|---|
|
||
| **WhatsApp** | ✅ Live | 15 | Meta Cloud API Webhook `/whatsapp/webhook` |
|
||
| **Web-Formular** | ✅ Live | 7 | `/api/submit` (Multipart-Formular) |
|
||
| **Telegram** | ⚠️ 1 Test-Eintrag | 1 | Nicht im Chatbot implementiert — wird extern behandelt |
|
||
|
||
Der existierende Meta System User Token (permanent, expires: 0) hat bereits folgende Scopes:
|
||
- `instagram_basic` ✅
|
||
- `instagram_content_publish` ✅
|
||
- `pages_read_engagement` ✅
|
||
- `pages_show_list` ✅
|
||
- `whatsapp_business_management` ✅
|
||
- `whatsapp_business_messaging` ✅
|
||
|
||
**Das bedeutet:** Instagram und Facebook Messenger könnten über die bestehende Meta-Infrastruktur integriert werden, ohne neue Berechtigungen!
|
||
|
||
---
|
||
|
||
## Kanal-Analyse (sortiert nach Geschwindigkeit der Umsetzbarkeit)
|
||
|
||
### 🔥 Kanal 1: Telegram (Bot API) — *schnellster Gewinn*
|
||
|
||
| Kriterium | Bewertung |
|
||
|---|---|
|
||
| **Aufwand** | 3–4 Stunden |
|
||
| **API-Typ** | Offizielle REST API, sehr gut dokumentiert |
|
||
| **Integration** | Webhook-Pattern wie WhatsApp: Telegram POSTed Updates → unser Endpoint antwortet |
|
||
| **Message-Typen** | Text, Foto, Video, Audio, Voice, Standort, Dokumente |
|
||
| **Kosten** | Kostenlos |
|
||
| **DSGVO** | ⚠️ Telegram ist in Dubai ansässig, Server global verteilt. Datenschutzerklärung muss Telegram als Auftragsverarbeiter nennen. ABER: Nutzer wählen Telegram selbst → ihre Entscheidung. Keine Gesundheitsdaten o.Ä. → vertretbares Risiko. |
|
||
|
||
**Technische Umsetzung:**
|
||
- Bot via @BotFather erstellen → API-Token
|
||
- Neuer Endpoint: `POST /telegram/webhook` in `app.py`
|
||
- Webhook-URL setzen: `https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://chat.datenhimmel.work/telegram/webhook`
|
||
- Parser-Funktion: Telegram-Update → Submission-DB-Schema mappen
|
||
- Media-Download via `https://api.telegram.org/file/bot<TOKEN>/<file_path>`
|
||
- Anti-Spam: Gleiche GDPR-Lösch-Logik wie WhatsApp
|
||
|
||
**Status:** Ein Test-Eintrag existiert bereits in der DB → Telegram wurde schon mal angetestet. Jetzt sauber implementieren.
|
||
|
||
---
|
||
|
||
### 🔥 Kanal 2: Instagram Direct Messages — *Meta-API, fast geschenkt*
|
||
|
||
| Kriterium | Bewertung |
|
||
|---|---|
|
||
| **Aufwand** | 4–6 Stunden |
|
||
| **API-Typ** | Meta Graph API (gleiche Infrastruktur wie WhatsApp!) |
|
||
| **Integration** | Instagram Professional Account an App koppeln → Webhook konfigurieren → Nachrichten landen im gleichen Webhook-Endpoint |
|
||
| **Message-Typen** | Text, Bilder, Videos, Story-Replies, Link-Attachments |
|
||
| **Kosten** | Kostenlos (Teil der Meta Graph API) |
|
||
| **DSGVO** | ⚠️ Meta = US-Konzern. ABER: Gleiche Rechtsgrundlage wie WhatsApp-Integration. Standardvertragsklauseln. Datenschutzerklärung ist bereits Meta-konform (WhatsApp-Teil). Instagram DM ist weniger invasiv als WhatsApp (keine Telefonnummer zwingend erforderlich). |
|
||
|
||
**Technische Umsetzung:**
|
||
1. Instagram Professional Account mit der Meta-App "Brettspiel-News.de" verbinden
|
||
2. Im Meta Developer Dashboard: Webhook-Produkt `instagram` hinzufügen
|
||
3. Webhook-Feld `messages` abonnieren → Test-Send von Instagram
|
||
4. Neuer Handler in `app.py` für Instagram-Events (gleicher Webhook-Endpoint, anderer `object`-Typ: `instagram`)
|
||
5. Message-Format-Mapper: Instagram-Nachricht → Submission-Schema
|
||
6. Media-Download via Instagram Graph API (Media-URLs sind kurzlebig — direkt downloaden!)
|
||
|
||
**PITFALL:** Instagram-Webhooks nutzen das GLEICHE Webhook-Endpoint-Format wie WhatsApp, aber mit `"object": "instagram"` statt `"object": "whatsapp_business_account"`. Kann also im selben `/whatsapp/webhook`-Endpoint behandelt werden — nur eine Fallunterscheidung nötig.
|
||
|
||
---
|
||
|
||
### 🔥 Kanal 3: Facebook Messenger — *größte Reichweite unter Brettspielern*
|
||
|
||
| Kriterium | Bewertung |
|
||
|---|---|
|
||
| **Aufwand** | 6–8 Stunden |
|
||
| **API-Typ** | Meta Graph API (Send/Receive API) |
|
||
| **Integration** | Facebook Page an App koppeln → Webhook konfigurieren → Nachrichten verarbeiten |
|
||
| **Message-Typen** | Text, Bilder, Videos, Audio, Dateien, Quick Replies, Templates |
|
||
| **Kosten** | Kostenlos (24h-Standard-Messaging-Fenster, danach nur Message-Tags) |
|
||
| **DSGVO** | ⚠️ Wie Instagram: Meta-US. ABER: Facebook-Seiten-Admin hat geteilte Verantwortlichkeit mit Meta (Art. 26 DSGVO). Muss in Datenschutzerklärung explizit genannt werden. Page-Admin-Tools geben Einblick in Datenverarbeitung. |
|
||
|
||
**Technische Umsetzung:**
|
||
1. Facebook Page "Brettspiel News" mit der Meta-App verbinden (Page Access Token)
|
||
2. Meta Developer Dashboard: Webhook-Produkt `messenger` hinzufügen
|
||
3. Webhook-Felder `messages` und `messaging_postbacks` abonnieren
|
||
4. Page abonnieren (ohne Subscription kommen keine Events!)
|
||
5. Handler für `"object": "page"` im Webhook-Endpoint
|
||
6. Messenger-Send-API für Antworten (POST `/{page_id}/messages`)
|
||
7. Media-Handling: Messenger-Attachments → Download via URL (authorisiert mit Page Token)
|
||
8. 24h-Fenster beachten: Nach 24h nur noch per Message-Tag antworten
|
||
|
||
**PITFALL:** Messenger hat ein 24-Stunden-Fenster für freie Antworten. Danach nur noch per Message-Tag (z.B. `HUMAN_AGENT`, `POST_PURCHASE_UPDATE`). Unsere Auto-Replies müssen innerhalb von 24h erfolgen — was bei Echtzeit-Antworten gegeben ist.
|
||
|
||
---
|
||
|
||
### ⚠️ Kanal 4: Signal (via signal-cli) — *datenschutzfreundlich, aber aufwendig*
|
||
|
||
| Kriterium | Bewertung |
|
||
|---|---|
|
||
| **Aufwand** | 12–16 Stunden + laufender Wartungsaufwand |
|
||
| **API-Typ** | Keine offizielle API. signal-cli (Open Source, Java) als REST-Wrapper |
|
||
| **Integration** | Signal-Telefonnummer registrieren → signal-cli als Daemon → REST-Endpoint exposed → Polling oder Webhook-ähnlich |
|
||
| **Message-Typen** | Text, Bilder, Videos, Dateien, Gruppen (eingeschränkt) |
|
||
| **Kosten** | Kostenlos (Signal selbst), aber: dedizierte Telefonnummer nötig (~5–10€/Monat) |
|
||
| **DSGVO** | 🟢 Bester Datenschutz aller Optionen: Signal ist E2E-verschlüsselt, non-profit, kein US-Datenzugriff. ABER: signal-cli ist ein inoffizieller Client — rechtliche Grauzone. Theoretisch DSGVO-freundlich, praktisch nicht auditierbar. |
|
||
|
||
**Technische Umsetzung:**
|
||
1. Dedizierte SIM-Karte / VoIP-Nummer für Signal registrieren
|
||
2. signal-cli installieren + als systemd-Daemon einrichten
|
||
3. REST-Mode aktivieren: `signal-cli daemon --http-listen 127.0.0.1:8080`
|
||
4. Polling-Loop oder lokalen Webhook via nginx auf die REST-API von signal-cli
|
||
5. Parser: Signal-Nachrichten-Format → Submission-Schema
|
||
6. Media: signal-cli lädt Attachments automatisch → lokaler Pfad referenzieren
|
||
7. Gruppen-Kommunikation: Signal-Gruppen sind verschlüsselt — nicht moderierbar vor Empfang
|
||
|
||
**PITFALLS:**
|
||
- signal-cli bricht bei größeren Updates von Signal regelmäßig → Wartungsaufwand
|
||
- Telefonnummer kann von Signal gebannt werden, wenn als Bot erkannt
|
||
- Kein offizieller Support — bei Problemen auf sich allein gestellt
|
||
- Gruppen-Nachrichten: Bot muss Gruppenmitglied sein (Einladung nötig)
|
||
|
||
**Fazit:** Nur umsetzen, wenn Datenschutz-Enthusiasten explizit Signal fordern. Strategisch wertvoll als DSGVO-Vorzeigekanal, aber operativ teuer.
|
||
|
||
---
|
||
|
||
### 🎮 Bonus-Kanal 5: Discord — *Gaming-Community, einfach integrierbar*
|
||
|
||
| Kriterium | Bewertung |
|
||
|---|---|
|
||
| **Aufwand** | 3–5 Stunden |
|
||
| **API-Typ** | Offizielle REST + Gateway (WebSocket) API |
|
||
| **Integration** | Discord Bot App → Webhook oder Gateway-Events → Handler |
|
||
| **Kosten** | Kostenlos |
|
||
| **DSGVO** | ⚠️ Discord = US-Unternehmen. Standardvertragsklauseln nötig. Aber: Gaming-Community ist Discord-affin — viele Brettspiel-Discords existieren bereits. |
|
||
|
||
---
|
||
|
||
## DSGVO-Zusammenfassung
|
||
|
||
| Kanal | US-Datenübermittlung | Einwilligung nötig? | Auftragsverarbeiter |
|
||
|---|---|---|---|
|
||
| WhatsApp | ✅ (Meta US) | Ja (Double Opt-In empfohlen) | Meta Platforms Inc. |
|
||
| Instagram | ✅ (Meta US) | Ja | Meta Platforms Inc. |
|
||
| Messenger | ✅ (Meta US) | Ja | Meta Platforms Inc. (geteilte Verantwortung) |
|
||
| Telegram | ⚠️ (Dubai, nicht US/EU) | Empfohlen | Telegram FZ-LLC |
|
||
| Signal | ❌ (E2E, non-profit) | Nein (Datenschutz per Design) | Keiner (direkte Kommunikation) |
|
||
| Discord | ✅ (US) | Empfohlen | Discord Inc. |
|
||
|
||
**Generelle DSGVO-Maßnahmen (für alle Kanäle):**
|
||
1. Datenschutzerklärung um jeden Kanal erweitern
|
||
2. Double Opt-In: `VERIFICATION_REQUIRED=1` in `.env` aktivieren
|
||
3. Löschlogik: `DELETE /submission/<id>` bereits implementiert — GDPR-Request manuell auslösbar
|
||
4. Datenminimierung: Wir speichern nur `sender_id`, `sender_name`, `content`, `media_path` — keine Metadaten (IP, Standort, Gerätedaten)
|
||
5. Server-Standort: Deutschland (netcup) — DSGVO-konformes Hosting
|
||
|
||
**Wichtig:** Für Meta-Kanäle (WhatsApp, Instagram, Messenger) sollte die Datenschutzerklärung einen expliziten Hinweis enthalten, dass Nachrichten über Meta-Server in die USA geleitet werden und der Nutzer dem durch Nutzung des jeweiligen Kanals zustimmt.
|
||
|
||
---
|
||
|
||
## Rangliste: Was zuerst?
|
||
|
||
```
|
||
┌───────┬─────────────────┬──────────┬──────────┬──────────┬──────────┐
|
||
│ Rang │ Kanal │ Aufwand │ Nutzen │ DSGVO │ Prio │
|
||
├───────┼─────────────────┼──────────┼──────────┼──────────┼──────────┤
|
||
│ 1. │ Telegram │ 3–4 h │ Hoch │ Mittel │ 🔥🔥🔥 │
|
||
│ 2. │ Instagram │ 4–6 h │ Mittel │ Mittel │ 🔥🔥 │
|
||
│ 3. │ Facebook Msgr │ 6–8 h │ Sehr hoch│ Mittel │ 🔥🔥 │
|
||
│ 4. │ Discord │ 3–5 h │ Mittel │ Mittel │ 🔥 │
|
||
│ 5. │ Signal │ 12–16 h │ Niedrig │ Grün │ ⚡ │
|
||
└───────┴─────────────────┴──────────┴──────────┴──────────┴──────────┘
|
||
```
|
||
|
||
**Empfehlung:** Starte mit **Telegram + Instagram** parallel (beide zusammen ~8h), dann **Facebook Messenger** (~8h). Discord und Signal sind Optional.
|
||
|
||
---
|
||
|
||
## Implementierungs-Roadmap
|
||
|
||
### Phase 1: Telegram (1 Tag)
|
||
- [ ] Bot mit @BotFather erstellen, Token in `.env`
|
||
- [ ] Endpoint `POST /telegram/webhook` in `app.py`
|
||
- [ ] Parser: Telegram-Update → `submissions`-Schema
|
||
- [ ] Media-Download via Telegram File API
|
||
- [ ] Webhook-URL registrieren, Test-Nachricht senden
|
||
- [ ] Deployment + Tunnel-Verifikation
|
||
|
||
### Phase 2: Instagram (1 Tag)
|
||
- [ ] Instagram Professional Account mit Meta-App verbinden
|
||
- [ ] Webhook `instagram` im Meta Developer Dashboard konfigurieren
|
||
- [ ] Handler im WhatsApp-Webhook: `object == "instagram"` Fall
|
||
- [ ] Message-Mapper + Media-Download
|
||
- [ ] Test: Instagram DM an verknüpften Account senden
|
||
- [ ] Deployment + Verifikation
|
||
|
||
### Phase 3: Facebook Messenger (1–2 Tage)
|
||
- [ ] Facebook Page mit App verbinden, Page Access Token holen
|
||
- [ ] Webhook `messenger` konfigurieren + Page abonnieren
|
||
- [ ] Handler im Webhook für `object == "page"`
|
||
- [ ] Messenger Send API für Antworten
|
||
- [ ] Media-Handling (Attachments über Messenger Platform API)
|
||
- [ ] 24h-Fenster-Logik für Antworten
|
||
- [ ] Test + Deployment
|
||
|
||
### Phase 4 (Optional): Discord + Signal
|
||
- [ ] Discord: Bot App erstellen, Gateway verbinden, Commands
|
||
- [ ] Signal: signal-cli installieren, Daemon, REST-Integration
|
||
|
||
---
|
||
|
||
## Nächster Schritt
|
||
|
||
Soll ich direkt mit **Phase 1 (Telegram)** loslegen? Der Bot kann in ~3 Stunden live sein, und wir haben schon einen Test-Eintrag in der DB. Wenn du grünes Licht gibst, schreibe ich den Code, deploye und verifiziere. 🚀
|