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. Bei direkter Einbettung über api-key steht im Verlauf nur das Löschen einzelner Konversationen zur Verfügung; „Verlauf leeren" verlangt einen geheimen Schlüssel und erscheint deshalb erst in der Server-to-Server-Einbettung.
• 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

warnung

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

info

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.

Wie im Playground gehört der Verlauf der Vorschau zur getesteten Agent-Version: Testkonversationen tauchen nicht in „Meine Chats" auf. In den Chat-Protokollen sind sie wie jede andere Konversation dokumentiert.