Ein Wissensdatenbank-Chat-Widget mit Lead-Erfassung einbetten

Machen Sie Ihre Dokumentation zum Assistenten an der Tür

Ihre Wissensdatenbank enthält bereits die Antworten, die Ihre Besucher suchen. Ein eingebettetes Chat-Widget bringt diese Antworten als konversationelle Eingangstür auf Ihre Website: Besucher stellen Fragen, das Widget führt dieselbe hybride RAG-Pipeline und dieselbe Agent-Infrastruktur aus, die Ihre internen Teams nutzen, und die Antworten kommen mit Zitaten aus den Workspaces, die Sie freigeben möchten. Dieses Tutorial geht das Einbetten des Widgets durch, die Kontrolle darüber, was es antwortet, die Lead-Erfassung und die korrekte CORS-Einrichtung - vom Admin-Panel zu einem funktionierenden Snippet in wenigen Minuten.

Das zweistufige Embed: ein Loader und ein sandboxed iframe

Das Widget ist um ein sicherheitsorientiertes Embed-Pattern herum gebaut. Statt Markup und Stile in Ihre Seite zu injizieren, kommt das Widget in zwei Schritten:

1. Das Loader-Skript. Fügen Sie ein einziges Script-Tag zur Website hinzu, das auf Ihren Widget-Dienst mit der Widget-ID zeigt. Der Loader ist eine kleine JavaScript-Datei, die ein iframe in der Host-Seite erstellt.
2. Das iframe-Panel. Das iframe lädt eine eigenständige Preact-Anwendung - als IIFE-Bundle mit Inline-CSS kompiliert -, die den schwebenden Button, das Chat-Panel und jede Interaktion in ihrem eigenen Dokument zeichnet.

<script src="https://ihre-simmetric-chat.com/widget/loader.js?widgetId=WIDGET_ID"></script>

Warum ein iframe? Weil die Interpolation von Zeichenketten nicht vertrauenswürdiger Inhalte in eine Host-Seite der klassische XSS-Pfad ist. Die Widget-Oberfläche in einem sandboxed iframe mit opaker Herkunft laufen zu lassen, entfernt diese Risikoklasse vollständig: Chat-Inhalte werden nie im Kontext Ihrer Seite ausgeführt. Die alten Embed-Routen per Zeichenketten-Interpolation wurden genau aus diesem Grund aus dem Produkt entfernt, daher ist das zweistufige Pattern keine Option unter vielen - es ist das Embed.

Die Kommunikation zwischen iframe und Seite läuft über ein kleines versioniertes postMessage-Protokoll (Nachrichtentypen simmetric:*), das das Öffnen/Schließen des FAB, das Umfärben des FAB und die Session-Storage-Handshakes handhabt. Beide Seiten validieren jede eingehende Nachricht gegen das exakt erwartete contentWindow, sodass zwischen verschiedenen iframes gefälschte Nachrichten ignoriert werden.

Das Widget erstellen und auf Wissen zeigen

Alles beginnt im Admin-Panel:

1. Erstellen Sie ein Widget unter Einstellungen → Widgets. Die Erstellung ist lizenzgebunden (widget_enabled) und respektiert das numerische Widget-Limit der Stufe.
2. Verknüpfen Sie das Widget mit einem oder mehreren Workspaces. Die Workspace-Whitelist ersetzt atomar alle vorherigen Verknüpfungen, daher ist die Schichtung des Wissensdatenbank-Zugriffs eine Frage dessen, welche Workspaces angehängt werden.
3. Konfigurieren Sie das Branding: Primärfarbe, Bot-Name, Logos, Position (unten rechts oder unten links). Community-Stufen-Deployments erhalten sinnvolle Standardwerte, wenn Felder leer sind; vollständige Anpassung und White-Labeling sind Enterprise-Flags.
4. Kopieren Sie das Embed-Snippet in das HTML Ihrer Website.

Da Widgets pro Workspace definiert sind, ist das Wissen, aus dem ein Widget schöpfen kann, exakt die Vereinigung der Wissensdatenbanken der verknüpften Workspaces - nicht mehr. Ein Support-Widget kann den öffentlichen Dokumentations-Workspace sehen, ohne je die Daten interner Projekte zu berühren.

Der Antwort-Model-Pin: serverseitig aufgelöst

Eine neuere Ergänzung zählt für die Qualitätskontrolle: Die Konfiguration jedes Widgets kann einen bestimmten LLM-Provider und ein Modell auswählen, die die Chat-Antworten dieses Widgets bedienen. Der Pin wird auf der Widget-Zeile gespeichert und serverseitig bei jeder Chat-Anfrage aufgelöst - er kommt nie vom Client, vom Widget-Proxy oder vom Browser des Besuchers. Ein gepinntes Modell hat Vorrang vor dem Workspace-Standard, und Widgets ohne Pin behalten die Standard-Auflösungskette. In der Praxis: Ihr Marketing-Widget kann auf genau dem Modell laufen, das Sie für öffentliche Antworten verifiziert haben, unabhängig davon, was jemand clientseitig manipuliert.

Lead-Erfassung, die Besucher respektiert

Die Lead-Erfassung des Widgets ist für die Realität eines öffentlichen Formulars gebaut: Missbrauch konzentriert sich dort, wo Daten gesammelt werden, daher ist der Lead-Endpunkt bewusst auf 3 Anfragen pro Stunde pro Quelle begrenzt (mit dem für den Nutzer sichtbaren Limit). Der Ablauf:

• Der Besucher sieht eine Einwilligungsbarriere zu personenbezogenen Daten, bevor er chattet - eine ausdrückliche Anerkennung, wie die Daten behandelt werden, kein unten versteckter Link zu einer Richtlinie.
• Eine Lead-Karte sammelt Kontaktdaten während oder nach der Konversation, und Einsendungen landen im Lead-Postfach des Widgets im Admin-Panel, mit CSV-Export für Ihre Pipeline.
• Sitzungen sind aus Designgründen anonym: Der Server erstellt eine Sitzung mit einem 256-Bit-Token und 24 Stunden Ablauf, und jede weitere Anfrage wird dagegen validiert. Die Limits pro Sitzung (20 Nachrichten pro Stunde, 5 Konversationen pro Tag) liefern bei Überschreitung ein 429 mit retryAfter-Hinweis, und die Oberfläche zeigt eine Rate-Limit-Warnung statt still zu scheitern.

Rate Limits sind Teil der Vertrauensgeschichte, kein Nachgedanke: Eine öffentliche Chat-Oberfläche sollte unter Last oder Missbrauch anmutig degradieren, und der Lead-Limiter ist die engste der drei Limiter auf der Widget-Seite.

CORS: per Design standardmäßig geschlossen

Widget-Verkehr überquert per Definition Origins, daher ist CORS Teil der Sicherheitsoberfläche statt ein Nachgedanke. Jedes Widget trägt seine eigene allowedOrigins-Liste, die im Admin-Panel bearbeitet werden kann. Zur Laufzeit validiert eine dynamische CORS-Middleware den Origin-Header jeder Anfrage gegen die Liste dieses Widgets - Anfragen von nicht erlaubten Origins werden beim Preflight abgewiesen, und die Middleware schlägt fail-closed fehl: Kann die Origin-Prüfung die Datenbank nicht erreichen, wird der Zugriff verweigert statt gewährt.

Konfigurieren Sie es in einem Durchgang:

• Fügen Sie die Origins Ihrer Website (Schema und Host, ohne Spielereien mit dem abschließenden Schrägstrich) zu den erlaubten Origins des Widgets hinzu.
• Denken Sie daran, dass Subdomain-Varianten als getrennte Origins zählen - beispiel.de und www.beispiel.de sind zwei Einträge.
• Nutzen Sie https://-Origins in der Produktion; der Widget-Dienst spricht dieselben URL-Regeln wie der Rest des Stacks.

Alles andere - die Loader-URL, das iframe, der Session-Bootstrap, der SSE-Chat-Stream - nutzt denselben Host, auf dem Sie den Widget-Dienst deployen, daher gibt es genau einen Ort, an dem Origin-Vertrauen entschieden wird: die erlaubte Liste des Widgets.

Was wo läuft

Eine schnelle Orientierungskarte, denn das Widget berührt drei Prozesse:

• Hauptserver - Widget-CRUD und Branding, Workspace-Verknüpfung, die interne API, die der Widget-Dienst mit seinem API-Schlüssel aufruft, und Lead/Analytics-Endpunkte für Administratoren. Der gesamte interne Router liefert 402, wenn das Widget-Feature aus ist.
• Widget-Dienst - die öffentliche Embed-Oberfläche: JS-Loader, iframe-HTML, Sitzungserstellung, Auslieferung der gecachten Konfiguration, der SSE-Proxy des Chats zum Hauptserver und der Lead-Endpunkt. Er authentifiziert sich beim Hauptserver mit einem WIDGET_API_KEY und bringt eigene Rate Limiter mit.
• Das iframe - der IIFE-Preact-Client mit dem Chat-Lebenszyklus: Sitzungserstellung, SSE-Streaming Token für Token, Zitatanzeige, vorgeschlagene Fragen und Einwilligungsbarrieren.

Der Chat-Proxy leitet dasselbe Ereignisformat wie die interne Streaming-API weiter - Statusmeldungen, Plan-Ankündigungen, gestreamte Tokens, Zitate und terminale done/error-Ereignisse -, sodass alles, was Ihr Team in einem Workspace-Chat sieht, Ihre Besucher im Widget erleben.

Startcheckliste

• Widget erstellt, Lizenzfeature aktiv, Workspaces verknüpft
• Branding gesetzt; White-Label-Flag, wenn das Widget nicht die Produktmarke tragen soll
• Antwort-Model-Pin auf der Widget-Zeile gesetzt (serverseitig aufgelöst)
• Erlaubte Origins decken jede Website und Subdomain ab, die es einbetten wird
• Lead-Erfassung end-to-end verifiziert: Einwilligungsbarriere, Einsendung, Admin-Postfach, CSV-Export
• Rate Limits verstanden: 3 Leads/Stunde, 20 Nachrichten/Stunde pro Sitzung, 5 Konversationen/Tag

Von dort ist das Widget ein Drop-in: ein Script-Tag, eine erlaubte Liste, eine Wissensdatenbank, der Sie bereits vertrauen. Wenn Ihre Besucher Fragen stellen, erhalten sie Antworten, die genau auf den von Ihnen gewählten Workspaces fußen - mit einer Lead-Erfassungs-Pipeline, die höflich zu Menschen und streng zu Bots ist.

Lies die vollständige Anleitung in der Doku →