Widgets
Widgets ermöglichen es, einen Agent als Chat-Komponente in externe Websites oder Anwendungen einzubetten. So können Unternehmen z. B. einen KI-gestützten Helpdesk auf der eigenen Website oder in einem Kundenportal bereitstellen.
Jedes Widget ist mit genau einem Agent verknüpft und kann individuell konfiguriert werden — von der Chat-Darstellung über die Funktionalität bis hin zu Farben und Avatar. Pro Workspace können mehrere Widgets erstellt werden.
Widget erstellen
Beim Erstellen eines Widgets wird konfiguriert:
- Name: Interner Name zur Identifikation des Widgets.
- Beschreibung: Kurze Erklärung zum Einsatzzweck des Widgets.
- Agent: Der Agent, der das Widget antreibt. Es wird jeweils die aktive Version des Agents verwendet.
Chat-Einstellungen
Die Chat-Einstellungen bestimmen, welche Funktionen im Widget verfügbar sind:
- Chat Header: Zeigt den Header mit Icon, Anzeigename und einer Schaltfläche zum Neuladen der Konversation.
- Anzeigename: Der Name, der Benutzern im Widget-Header angezeigt wird.
- Verlauf anzeigen: Zeigt die bisherige Chat-Historie an. Wenn deaktiviert, startet jeder Chat ohne sichtbaren Verlauf. Im Gegensatz zu „Meine Chats" (Backend) wird im externen Widget keine persönliche, dauerhafte Historie geführt.
- Disclaimer anzeigen: Zeigt einen Haftungsausschluss beim ersten Öffnen des Chats.
- Feedback aktivieren: Zeigt Daumen-hoch/runter-Buttons zur Bewertung von Antworten.
- Temporärer Chat: Ermöglicht einen Button für temporäre Chats im Widget. Ist der temporäre Modus aktiv, werden Konversationen nicht dauerhaft auf dem Server gespeichert und temporäre Dateien automatisch gelöscht.
- Node Updates aktivieren: Zeigt Echtzeit-Updates während der Agent längere Anfragen verarbeitet.
Standalone-Modus
- Als eigenständiges Widget verwenden: Bestimmt, ob der Chat als Popup-Widget (mit abgerundeten Ecken und Schatten) oder als eingebettete Vollansicht (ohne Rahmen, fügt sich in die umgebende Seite ein) dargestellt wird.
Theming
Jedes Widget kann visuell an das eigene Branding angepasst werden.
Primärfarben
- Main: Die Hauptfarbe des Widgets (z. B. Buttons, Hervorhebungen).
- Light: Helle Variante der Hauptfarbe.
- Dark: Dunkle Variante der Hauptfarbe.
- Kontrasttext: Textfarbe auf farbigen Hintergründen.
- Senden-Icon: Farbe des Senden-Buttons.
Avatar
- Avatar-Hintergrund: Hintergrundfarbe des Avatars.
- Avatar-Bild: Ein eigenes SVG-Icon, das den Standard-Avatar ersetzt.
Integration
Um ein Widget in eine Website einzubetten, wird ein HTML-Snippet bereitgestellt, das in die Seite integriert werden muss:
<ai-hub-chat language="de" height="690" width="570" integration-location="#IHR_STANDORT" api-key="#IHR_API_KEY" widget-id="[WIDGET_ID]" />
<script src="[SCRIPT_URL]" type="module" defer></script>
Das Snippet kann direkt aus der Widget-Übersicht in die Zwischenablage kopiert werden.
Attribute
| Attribut | Erforderlich | Beschreibung |
|---|---|---|
widget-id | Ja | Die ID des Widgets (wird automatisch eingesetzt) |
api-key | Ja | Der API-Schlüssel für die Authentifizierung |
integration-location | Ja | Ein frei wählbarer Bezeichner, der in den Chat-Protokollen anzeigt, wo das Widget eingebettet ist (z. B. „Homepage", „Support-Seite") |
language | Ja | Sprachcode für die Oberfläche (z. B. de, en) |
height | Ja | Höhe des Widgets in Pixeln |
width | Ja | Breite des Widgets in Pixeln |
api-url | Nein | Überschreibt den API-Endpunkt für die Server-to-Server-Einbettung über einen eigenen Proxy |
Für die Integration wird ein API-Schlüssel vom Typ Widget benötigt, der direkt mit diesem Widget verknüpft ist. Bei öffentlichen Widgets sollte ein öffentlicher Schlüssel mit konfigurierten erlaubten Domains verwendet werden.
Storybook & Code-Snippets
Zusätzlich zum Embed-Code-Snippet stehen direkt in den Widget-Einstellungen eine Storybook-Anleitung und Code-Snippets zur Verfügung. Diese zeigen Beispiele für die Einbindung in unterschiedlichen Umgebungen (z. B. frameworkspezifisch).
Events & Tracking
Die Web-Component löst bei jeder relevanten Benutzeraktion ein eigenes DOM-Event aus. Die einbettende Seite kann diese Events abhören und so die Nutzung des Chats messen, ohne Zugriff auf die Inhalte der Konversation zu benötigen.
Die Events werden auf document ausgelöst und dort per addEventListener abgehört:
document.addEventListener("chat_message_sent", (event) => {
console.log(event.detail.properties.textLength);
});
Aufbau des detail-Objekts
Alle aktuellen Events liefern ein detail-Objekt mit folgenden Feldern:
| Feld | Beschreibung |
|---|---|
event | Name des Events — identisch mit dem Namen, auf den Sie hören |
version | Version der Event-Struktur (derzeit immer 1) |
sessionId | Kennung der Session (optional) |
timestamp | Zeitpunkt des Events im ISO-8601-Format |
pageUrl | URL der Seite, auf der das Event ausgelöst wurde |
referrer | Referrer-URL der Seite (optional) |
userId | Kennung des Benutzers (optional) |
properties | Event-spezifische Zusatzinformationen — entfällt bei Events ohne eigene Eigenschaften |
Verfügbare Events
| Event | Wird ausgelöst | properties |
|---|---|---|
chat_opened | Beim initialen Laden der Web-Component | — |
chat_closed | Beim Schließen der Web-Component | — |
chat_conversation_started | Wenn eine neue Konversation beginnt oder eine bestehende ausgewählt wird | — |
chat_conversation_ended | Wenn eine Konversation beendet wird. Folgt darauf ein chat_conversation_started, hat der Benutzer eine neue Konversation begonnen oder eine andere gewählt | — |
chat_message_sent | Beim Absenden einer Nachricht — manuell oder per Klick auf einen Vorschlag | textLength (Anzahl Zeichen), hasAttachments (ob Dateien hochgeladen wurden), source ("suggestions" oder "enter") |
chat_link_clicked | Beim Klick auf einen Link innerhalb des Chats | linkTarget (URL des Links), location (Ort des Links, z. B. "Chat Message") |
chat_feedback_submitted | Beim Absenden von Feedback zu einer Nachricht | feedbackType ("Positive", "Negative" oder undefiniert), feedbackAction ("added" oder "removed") |
chat_suggestion_clicked | Beim Klick auf einen Vorschlag | suggestion (Text des Vorschlags) |
chat_history_cleared | Wenn der Benutzer den Konversationsverlauf löscht | — |
Veraltete Events
Diese Events existieren aus Kompatibilitätsgründen weiter, liefern aber kein detail-Objekt in der oben beschriebenen Form. Verwenden Sie für neue Integrationen den jeweiligen Nachfolger:
| Veraltetes Event | Nachfolger |
|---|---|
chatOnClose | chat_closed |
chatOnReset | chat_conversation_started |
Der AI Hub schreibt keine Analyse-Plattform vor und sendet selbst keine Tracking-Daten. Das Übersetzen der Events in ein bestehendes Analytics-Setup — etwa Google Analytics, Matomo oder einen Tag Manager — ist Aufgabe der einbettenden Anwendung. Prüfen Sie dabei, welche der übermittelten Felder nach Ihren Datenschutzvorgaben überhaupt erhoben werden dürfen.
Eine ausführliche Beschreibung mit Code-Beispielen pro Event finden Sie in der Events-Dokumentation im Storybook.
Vorschau
Über die Widget-Vorschau können alle erstellten Widgets live getestet werden, ohne sie in eine externe Website einbetten zu müssen. Wählen Sie ein Widget aus dem Dropdown, um die Vorschau zu laden.
