Chat-Widget & Support-Chat (ChatWidget)

Zweck

Das Chat-Widget ist ein einbettbarer Live-Chat für die eigene Website oder den Shop: Besucher chatten, die KI beantwortet Anfragen (mit optionalem Zugriff auf Kundendaten), und bei Bedarf übernimmt ein Support-Mitarbeiter den Chat in der Inbox. Das Modul hat zwei Seiten:

Route	Zweck	Zugang
/chat-widget	Admin + Support-Inbox (Widgets verwalten, Chats bearbeiten)	view:ChatWidget
/widget	das eingebettete Besucher-Widget (iframe auf der Kundenseite)	öffentlich (kein Login)

Voraussetzungen

- Für Verwaltung/Inbox: `view:FE_ChatWidget` und `view:ChatWidget`. - Zum Bearbeiten von Chats (Inbox): `do:HandleSupportChat` **oder** Zuweisung zum Widget. - Das eingebettete Widget braucht **keine** Anmeldung; es ist über einen signierten Embed-Token + Domain-Whitelist abgesichert.

Berechtigungen (CASL)

Action	Subject	Wirkung
view	FE_ChatWidget, ChatWidget	Verwaltung/Inbox aufrufbar
create/update/delete	ChatWidget	Widgets anlegen/konfigurieren/löschen, Zuweisungen pflegen
do	HandleSupportChat	Support-Chats annehmen/bearbeiten (Inbox)
view	WidgetConversation	Besucher-Konversationen einsehen
view	ViewAllSupportStats	Support-Feedback aller sehen (nicht nur eigene)

Admin: Widget verwalten

Unter /chat-widget legen Sie Widgets an und konfigurieren sie (Detail unter /chat-widget/:id):

• Allgemein: Name, Status, identityMode, KI an/aus, Handoff an/aus, systemPrompt, Daten-Scopes.
• Styling + Vorschau (/chat-widget/:id/customization): Live-Vorschau + Einbettungscode-Modal mit Plattform-Anleitung (Website-HTML, Shopify-Snippet) und Copy-Button. Über displayMode lässt sich das Widget als schwebende Bubble (widget, Default) oder eingebettet/Vollbild (inline) ausgeben — der Inline-Modus rendert das Widget direkt in einen Ziel-Container der Seite (Einbettung mit data-mode="inline" + data-target="#container"), ohne Launcher.
• Zuweisungen (/chat-widget/:id/assignments): Mitarbeiter, Abteilung oder Rolle zuweisen (ChatWidgetAssignment) — bestimmt, wer Chats dieses Widgets bearbeiten/benachrichtigt wird.
• Verfügbarkeit: respectAvailability (nur verfügbare Mitarbeiter benachrichtigen — nach Arbeitszeitmodell + Abwesenheiten) und availabilityOverrideEmployeeIds (immer benachrichtigen).

Identitäts-Modi

identityMode	Verhalten
anonymous	Kein Formular, sofort chatten.
name_email_optional	Name/E-Mail vorgeschlagen, aber optional (Default).
name_email_required	Name + E-Mail Pflicht vor der ersten Nachricht.
verified_customer	E-Mail/Kundennummer wird verifiziert (Code), bevor kundenspezifische Auskünfte erlaubt sind.

Support-Inbox

Im Tab Konversationen (/chat-widget/:id/conversations) bearbeiten Supporter die Chats:

• Liste links (Suche, Ungelesen, Status), Thread rechts (KI- + Mitarbeiter-Nachrichten + interne Notizen).
• Chat übernehmen (öffnet eine Vollbild-Inbox/Popout), zurück an die KI, erledigt.
• Schnellantworten per „/"-Befehl mit Variablen ({{name}} u. a.) — pro Widget gepflegt (cannedResponses).
• Besucher-Presence (online / inaktiv / weg) wird angezeigt.
• KI-Antwortvorschläge erscheinen als Vorschlags-Karte unter der Besucher-Nachricht; der Supporter übernimmt sie per Klick (statt automatisch zu senden).

Die KI schlägt Antworten vor und kann (bei verifizierten Kunden) z. B. eine Rechnung per Mail nachsenden. Die **Kontrolle** über das, was an den Besucher geht, bleibt beim Supporter. Verdächtige Anfragen (Prompt-Injection) werden intern erkannt (`suspiciousScore`) und neutral an den Support eskaliert.

Das eingebettete Widget (/widget)

Das Besucher-Widget wird per Loader-Script auf der Kundenseite eingebunden und als iframe (/widget) geladen — eine eigenständige App ohne Login, die nur die öffentlichen /public-widget/*-Endpunkte nutzt.

Absicherung:

• Embed-Token: kurzlebiger, signierter Token (GET /public-widget/:publicKey/embed-token) mit der gemeldeten Einbettungs-Origin.
• Domain-Whitelist: nur Hosts aus allowedDomains des Widgets dürfen einbetten (Wildcard-Unterstützung); sonst 403.
• Session-Token: nach Konversationsstart; nur als SHA-256-Hash gespeichert.

verified_customer — Verifizierung

Im Modus verified_customer gibt der Besucher E-Mail oder Kundennummer ein → ein 6-stelliger Code wird an die hinterlegte Adresse gesendet. Erst nach Bestätigung darf die KI kundenspezifische Auskünfte geben. Sicherheits-Eigenschaften:

• Kein Existenz-Leak: jede Anfrage erhält dieselbe neutrale Rückmeldung („falls ein Konto existiert …"); ein Code wird nur bei echtem Treffer versendet.
• Code SHA-256-gehasht, 15 Min gültig, max. 5 Versuche.

Datenmodell (Auszug)

• ChatWidget — name, publicKey, status, identityMode, aiEnabled, handoffEnabled, allowedDomains, styling, systemPrompt, cannedResponses, respectAvailability, availabilityOverrideEmployeeIds.
• WidgetConversation — Besucher-Session: visitorName/visitorEmail, status, assignedEmployeeId, authStatus (none/pending/verified), authCustomerId/authClientId.
• ChatWidgetAssignment — Zuweisung (assigneeType employee/department/role).

API/Schnittstellen (Auswahl)

Methode	Endpoint	Zweck	CASL
GET/POST	/api/chat-widgets	Widgets lesen/anlegen	view/create ChatWidget
PATCH/DELETE	/api/chat-widgets/:id	ändern/löschen	update/delete ChatWidget
GET/POST	/api/chat-widgets/:id/assignments	Zuweisungen	update ChatWidget
GET	/api/widget-conversations	Konversationen (Inbox)	view WidgetConversation
GET	/api/public-widget/:publicKey/config	Widget-Konfiguration	öffentlich
GET	/api/public-widget/:publicKey/embed-token	signierter Embed-Token	öffentlich (Domain-Whitelist)
POST	/api/public-widget/:publicKey/conversations	Konversation starten	öffentlich
POST	/api/public-widget/conversations/:id/messages	Besucher-Nachricht (KI antwortet via SSE)	öffentlich
POST	/api/public-widget/conversations/:id/verify/request · /verify/submit	Verifizierung (Code anfordern/bestätigen)	öffentlich

Weitere öffentliche Endpunkte: loader.js, …/feedback, …/end, …/presence, …/stream (SSE), …/attachments/:documentId, …/agent-avatar/:employeeId.

Verknüpfungen zu anderen Modulen

• Mail — die KI kann verifizierten Kunden Rechnungen per Mail nachsenden.
• Kunden — Ziel der Verifizierung (verified_customer).
• Mitarbeiter / Abteilungen / Rollen — Zuweisungs-Ziele.

Versionshinweise

• 2026-06-30: Anzeige-Modus displayMode (widget-Bubble vs. inline/Vollbild, eingebettet in einen Ziel-Container) ergänzt. Verifiziert an ChatWidgetDetailPage.tsx (WidgetStyling).
• 2026-06-06: Initiale Veröffentlichung. Einbettbares Chat-Widget (Loader, signierter Embed-Token, Domain-Whitelist, Shopify/Website-Einbettung), Identitäts-Modi inkl. verified_customer (Code-Verifizierung, kein Existenz-Leak), KI-Antwortvorschläge + interne Notizen + Schnellantworten, Support-Inbox mit Zuweisung/Verfügbarkeit/Presence, Prompt-Injection-Erkennung. Verifiziert an chatWidget.model.ts, chatWidget.router.ts, chatWidget.public.router.ts, routes.tsx, casl.ts.