:::note Versionsstatus Das veröffentlichte npm-SDK 0.1.4 mit gehostetem widget.js v15 unterstützt Teardown über remove() oder window.ChattyBox.destroy(): UI/Styles werden entfernt und ausstehende Initialisierung, Wiederholungen und Chats abgebrochen. v15-Chat nutzt höchstens 10 Versuche innerhalb eines 30-Sekunden-Planungsbudgets, nicht als hartes Request-Timeout. Headless-sendMessage() wiederholt nicht automatisch. :::

Anpassung des gehosteten Widgets

Passen Sie die vorgefertigte Oberfläche an, die von https://chattybox.ai/widget.js geladen wird. Kanonische Installationsbeispiele für Frameworks und Plattformen finden Sie in den Installationsleitfäden.

Vor der Anpassung

Erstellen Sie das Projekt, indexieren Sie seine Inhalte und überprüfen Sie repräsentative Antworten in Test Chat, bevor Sie Zeit in die Darstellung investieren. Die vollständige Reihenfolge finden Sie unter Erste Schritte.

Gehostetes Widget konfigurieren

1. Öffnen Sie Ihr Dashboard und wählen Sie Ihr Projekt aus.
2. Öffnen Sie den Tab Embed.
3. Sehen Sie sich das Erscheinungsbild und das Sprachverhalten des Widgets in der Vorschau an und speichern Sie beides.

Der Tab Embed steuert die Darstellung und erzeugt den Installationscode. Öffentliche Schlüssel werden jedoch separat verwaltet. Wenn Sie bereit für die Installation sind:

1. Öffnen Sie Public Keys und erstellen Sie einen Browserschlüssel.
2. Standardmäßig funktioniert der Schlüssel für Produktion, Vorschau, Staging und localhost. Für optionale Härtung aktivieren Sie unter Edit origins eine Einschränkung und tragen exakte Origins ein.
3. Kehren Sie zu Embed zurück, wählen Sie den Schlüssel aus und kopieren Sie das generierte Snippet.
4. Befolgen Sie die Installationsleitfäden für Ihre Plattform.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

Tipp

Gespeicherte Änderungen gelten bei der nächsten Initialisierung; bereits geöffnete Seiten müssen neu geladen werden. Die Dashboard-Vorschau ist ein Mock, nicht das gehostete Widget.

---

Visuelle Anpassung

ChattyBox verfügt über einen vollständig integrierten visuellen Editor. Sie können das Aussehen und Verhalten Ihres Widgets ohne Code an Ihre Marke anpassen.

Dashboard-Steuerelemente

1. Accent Color – Wählen Sie die Primärfarbe Ihrer Marke. Sie beeinflusst Launcher, wichtige Hervorhebungen und Nutzernachrichten.

2. Position – Wählen Sie, wo das Widget auf dem Bildschirm erscheint.

3. Header Title – Legen Sie den Titel fest, der oben im Chatfenster angezeigt wird.

4. Welcome Message – Passen Sie die erste Nachricht an, die Besucher beim Öffnen des Chats sehen.

Notiz

Der Editor bietet außerdem Hintergrund, Textfarbe und Symbol (Roboter, Emoji, URL oder Upload). Hochgeladene Symbole sind auf 512 KiB und PNG, JPEG, WebP, SVG, GIF oder ICO begrenzt; die gespeicherte Symbolgröße wird vom Loader derzeit nicht gelesen.

Erweiterte Optionen

Dashboard-Einstellungen und Skriptattribute

Das Verhalten des Widgets sollte größtenteils über das Dashboard verwaltet werden, damit Sie Ihre Website für einfache Änderungen nicht erneut bereitstellen müssen.

Verwenden Sie das Dashboard für Farben, Position, Symbol, Header-Titel, Willkommensnachricht, Sprachvoreinstellungen, Verwaltung öffentlicher Schlüssel, Scraping und Analytics.

Wenn Ihr Projekt Einschränkungen der Ursprünge öffentlicher Schlüssel verwendet, halten Sie diese Einschränkungen mit den Domains synchron, auf denen das Widget installiert ist.

Verwenden Sie Skriptattribute nur für Werte, die das Widget beim Laden der Seite benötigt:

• data-api-key identifiziert den öffentlichen Widget-Schlüssel.
• data-api-url gibt an, wohin das Widget Anfragen sendet. In der Produktion ist dies eine stabile https://...convex.site/chat-URL aus Ihrem Dashboard.
• data-locale fordert eine UI-Sprache nur bei Initialisierung und nur bei erlaubtem Script-Override an.
• data-color, data-position und data-debug="true" sind Ladezeit-Overrides bzw. Diagnostik; bevorzugen Sie gespeicherte Dashboard-Werte.

Wenn das Widget nach der Installation nicht erscheint, lesen Sie die Fehlerbehebung.

Für plattformspezifische Beispiele beginnen Sie mit Docusaurus, MkDocs, VitePress, WordPress oder GitBook.

Widget auf bestimmten Seiten ausblenden

Wenn Sie das Widget auf ausgewählten Seiten ausblenden müssen, können Sie dies mit CSS tun:

.chattybox-widget {
  display: none;
}

CSS-Ausblenden stoppt weder Initialisierung noch API-Anfragen oder Fehlerberichte und ist keine Consent- oder Datenschutzkontrolle. Um das Laden zu verhindern, schließen Sie das Script aus. Für clientseitige Routenwechsel oder den Widerruf der Einwilligung bietet das gehostete widget.js v15 window.ChattyBox.destroy(); das veröffentlichte SDK 0.1.4 verwendet remove() für denselben Teardown.

Benutzerdefinierte Integrationen

Benötigen Sie eine individuellere Einrichtung als mit dem gehosteten Widget? Erstellen Sie mit dem JavaScript-SDK Ihre eigene Oberfläche oder wenden Sie sich für Architekturhilfe an support@chattybox.ai.

Mehrsprachige Unterstützung

Das Widget löst seine UI-Locale bei der Initialisierung nach dem Projektmodus auf; es beobachtet weder Attribute noch clientseitige Routenwechsel.

Offiziell unterstützte Sprachen

Das Widget besitzt Kataloge für 14 Sprachen, alle LTR. Ein Katalog garantiert weder jede übersetzte Beschriftung noch Antwortqualität; einige Labels bleiben derzeit Englisch.

Sprache	Code
Englisch	en
Französisch	fr
Deutsch	de
Spanisch	es
Italienisch	it
Niederländisch	nl
Portugiesisch	pt
Polnisch	pl
Schwedisch	sv
Indonesisch	id
Estnisch	et
Finnisch	fi
Walisisch	cy
Tschechisch	cs

:::note UI-Sprache und Antworten Die UI-Locale wird nicht als Chat-Sprachparameter gesendet. Das Backend erkennt die Fragesprache und versucht sprachbewusstes Retrieval; Qualität und Antwortsprachen hängen von indexiertem Inhalt und Modell ab. Die Kataloge garantieren weder übersetzte Labels noch die Qualität oder Sprache der Antworten. :::

So funktioniert die Spracherkennung

Das Widget verwendet ein Kaskadensystem zur Erkennung:

1. Erlaubter Override – ein nichtleeres data-locale gewinnt nur, wenn allowLocaleOverride nicht false ist, auch im festen Modus.
2. Fester Modus – ohne erlaubten Override wird defaultLocale benutzt.
3. Auto-Modus – <html lang>, dann Browsersprache, dann defaultLocale.
4. Normalisierung – fr-CA kann zu fr werden; ein nicht unterstützter Wert wird sofort Englisch.

Sprache manuell überschreiben

Um eine bestimmte Sprache anzufordern, aktivieren Sie zuerst Allow Script Override und setzen dann data-locale vor dem Loader:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-locale="de"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

:::tip Anwendungsfall Das ist besonders nützlich für mehrsprachige Websites, bei denen jede Sprachversion eine eigene URL hat (z. B. /de/, /fr/). Setzen Sie data-locale passend zur Seitensprache und prüfen Sie die gerenderte Oberfläche. :::

Spracheinstellungen im Dashboard

Im App-Dashboard können Sie die Spracheinstellungen des Widgets pro Projekt konfigurieren:

• Auto-detect – nutzt Seitensprache vor Browsersprache.
• Fixed Language – nutzt die konfigurierte Sprache, außer ein Override ist erlaubt.
• Allow Script Override – Aktiviert oder deaktiviert die Überschreibung über das Attribut data-locale.

Sie finden diese Einstellungen in Ihrem Dashboard → Projekt → Tab Embed → Abschnitt Widget Language.

Sprache der Inhalte abgleichen

Indexieren Sie für ein nützliches mehrsprachiges Erlebnis öffentliche Inhalte in den Sprachen Ihrer Besucher und prüfen Sie die Quellen: Erkennung und Retrieval sind nicht garantiert. Gehen Sie dazu wie folgt vor:

1. Scrapen Sie alle Sprachversionen Ihrer Dokumentation mithilfe der Datei sitemap.xml.
2. Der Scraper versucht, die Sprache zu erkennen; prüfen Sie Inhalte und Quellen statt ein exaktes Ergebnis anzunehmen.
3. Retrieval versucht die erkannte Fragesprache zu bevorzugen, kann aber auf andere indexierte Inhalte zurückfallen.

Einrichtung im App-Dashboard: Verwenden Sie beim Konfigurieren des Scrapings Ihre sitemap.xml-URL (z. B. https://yourdocs.com/sitemap.xml), um Sprachversionen zu entdecken, und prüfen Sie anschließend die indexierten Seiten. Sitemaps umgehen weder Crawl-Limits noch Ausschlüsse.

Fehlerbehebung

Widget wird weiterhin auf Englisch angezeigt

• Hard Refresh als Diagnose – Laden Sie die Seite mit Ctrl+F5 oder Cmd+Shift+R neu und prüfen Sie anschließend im Netzwerkbereich des Browsers die Widget- und Übersetzungsanfragen.
• data-locale prüfen – Überprüfen Sie, ob das Attribut mit einem unterstützten Sprachcode korrekt gesetzt ist.
• Browsersprache überprüfen – Stellen Sie sicher, dass die bevorzugte Sprache Ihres Browsers korrekt eingestellt ist.
• lang im Seiten-HTML prüfen – Stellen Sie sicher, dass Ihre Seite <html lang="de"> (oder den passenden Code) enthält.

Quellen sind in der falschen Sprache

• Inhalte erneut scrapen – Stellen Sie sicher, dass alle Sprachversionen indexiert sind.
• sitemap.xml verwenden – Prüfen Sie, ob die gewünschten URLs tatsächlich indexiert wurden; Crawl-Limits und Ausschlüsse können sie auslassen.
• Anfragesprache prüfen – Die KI versucht, die Antwortsprache an die Sprache der Anfrage anzupassen.

Übersetzungen fehlen

• Unterstützte Sprachen prüfen – Nur die oben aufgeführten 14 Codes haben Kataloge; fehlende Labels können auf Englisch zurückfallen.

Best Practices

1. <html lang> auf Ihren Seiten setzen – Hilft bei Barrierefreiheit und Widget-Erkennung.
2. Während der Entwicklung mit data-locale testen – Überprüfen Sie, ob jede Sprache korrekt dargestellt wird.
3. Alle Sprachversionen scrapen – Verwenden Sie sitemap.xml zur Entdeckung und prüfen Sie die indexierten Seiten.
4. Echte Fragen prüfen – Das Dashboard bietet keinen Bericht zur Verteilung der Widget-Locales.