Zum Hauptinhalt springen

Fehlerbehebung

Verwenden Sie diese Seite, wenn das Widget installiert ist, sich aber nicht wie erwartet verhält.

Widget wird nicht angezeigt​

Überprüfen Sie zunächst die Browserkonsole. ChattyBox meldet dort fehlende erforderliche Attribute.

Häufige Ursachen:

  • Das Skript fehlt sowohl im ausgelieferten HTML als auch im Live-DOM.
  • Das Skript wurde zur falschen Vorlage, zum falschen Layout, zum falschen Tag-Manager-Container oder zum falschen CMS-Codebereich hinzugefügt.
  • Das Skript steht hinter einer Einwilligungsregel oder einem Tag-Manager-Auslöser, der nicht ausgelöst wurde.
  • Die Anwendungskomponente, die den Loader einbindet, wird auf dieser Route nicht ausgeführt.
  • Eine Inhaltssicherheitsrichtlinie blockiert https://chattybox.ai/widget.js.
  • CSS oder ein anderes Widget überlappt den Launcher.
  • Die bereitgestellte Konfiguration enthält widget.enabled: false.

Kleinster Fix:

  1. Öffnen Sie die bereitgestellte öffentliche Seite in einem Inkognito-Fenster.
  2. Suchen Sie in der Seitenquelle und im Elements-Panel des Browsers nach chattybox.ai/widget.js; ein per SDK oder JavaScript eingefügter Loader ist möglicherweise nur im Live-DOM zu sehen.
  3. Bestätigen Sie, dass das Skript einmal erscheint und data-api-key und data-api-url enthält.
  4. Fügen Sie das Skript, falls es fehlt, im globalen Footer, im App-Layout, im Docusaurus-Stamm oder im GTM-Trigger All Pages ein.

Bei konfigurationsverwalteten Projekten verhindert widget.enabled: false die Initialisierung des gehosteten Widgets und bewirkt, dass öffentliche POST /chat-Anfragen mit 403 Widget is disabled antworten, einschließlich Anfragen des Headless-SDK. Ändern Sie diese Einstellung über den Konfigurations-Deployment-Workflow und nicht durch Rotation des öffentlichen Schlüssels. Das Entfernen eines Loader-Skripts nach der Initialisierung entfernt das bereits gerenderte Widget nicht.

data-api-url fehlt​

Das Widget wird vorzeitig beendet, wenn data-api-url fehlt.

Verwenden Sie den vollständigen Ausschnitt aus dem Dashboard oder fügen Sie das erforderliche Attribut hinzu:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Verwenden Sie die API-URL aus Ihrem Dashboard, statt sie zu erraten. In der Produktion sollte es eine stabile URL im Format https://...convex.site/chat sein.

Generischer Fehler 401 Invalid API key​

Aus Sicherheitsgründen geben Widget-API-Endpunkte bei einem unbekannten, abgelaufenen oder wegen seiner Herkunft abgelehnten öffentlichen Schlüssel dieselbe generische Antwort 401 Invalid API key zurück. Die Antwort verrät nicht, welche Ursache vorliegt.

Häufige Ursachen:

  • Der öffentliche Widget-Schlüssel wurde falsch kopiert.
  • Der Schlüssel wurde gelöscht, ist abgelaufen oder stammt aus einem anderen Backend-Deployment als die API-URL.
  • Das Projekt oder der Eigentümer des Schlüssels wird gelöscht.
  • Die optionale Herkunftsbeschränkung ist für den Schlüssel aktiviert, aber die aktuelle Website-Herkunft ist nicht zugelassen.

Korrekturen:

  1. Öffnen Sie das Projekt im Dashboard ChattyBox.
  2. Öffnen Sie Installieren → Installation auf der Website, geben Sie die Website-URL ein und kopieren Sie ein geeignetes Snippet, sofern eines verfügbar ist.
  3. Wählen Sie auf derselben Seite unter Schlüssel und Domains für den Schlüssel im installierten Snippet Origins bearbeiten. Wenn Diesen Schlüssel auf bestimmte Origins beschränken aktiviert ist, fügen Sie die exakte Herkunft der Seite hinzu oder deaktivieren Sie die optionale Beschränkung. Protokoll, Hostname und Port müssen übereinstimmen: https://example.com, https://preview.example.com und http://localhost:3000 sind unterschiedliche Herkünfte. Für einzelne Pfade sind keine separaten Einträge erforderlich.
  4. Stellen Sie die Site erneut bereit oder veröffentlichen Sie sie erneut und testen Sie sie erneut in einem Inkognito-Fenster.

Ein gültiger Schlüssel für einen anderen Chatbot auf demselben Backend wählt normalerweise diesen Chatbot aus, statt einen 401 auszulösen; prüfen Sie das Projekt, wenn Antworten unerwartet unpassend sind. Schlüsselnamen wie „production“ und „staging“ erzwingen keine Umgebungen. Wenn Origin vorhanden ist, verwendet die HTTP-API diesen Header; die Herkunft aus Referer wird nur verwendet, wenn Origin fehlt. Ist Origin vorhanden, aber nicht zugelassen, ersetzt ein zulässiger Referer-Wert ihn nicht. Ein eingeschränkter Schlüssel lehnt jede Anfrage ab, deren so ausgewählte Herkunft fehlt, ungültig oder nicht zugelassen ist. Herkunftsbeschränkungen ersetzen keine Besucherauthentifizierung.

Nachrichtenlimits und Anfragelimits​

Prüfen Sie unter Abrechnung und Nutzung unter /settings/account das Nachrichtenkontingent, den Tarif und optionale PAYG-Budgets für Pro/Business. Chatbot testen und öffentlicher Chat verbrauchen gemeinsam das Nachrichtenkontingent des Eigentümers. Das Löschen von Unterhaltungen oder das Erstellen eines weiteren Schlüssels setzt dieses Kontingent nicht zurück.

Monatliche Kontingentfehler und kurzfristige Anfragelimits sind verschieden. Beachten Sie bei HTTP-Antworten 429 den Header Retry-After, sofern vorhanden, statt wiederholt Anfragen zu senden. Bei einem monatlichen Nachrichtenlimit warten Sie auf die Rücksetzung des Kontingents oder passen Sie den Tarif bzw. das zulässige PAYG-Budget an. Konversationen → Verlauf enthält den Gesprächsverlauf und ist keine Fehlerkonsole für einzelne Anfragen; prüfen Sie HTTP-Fehler im Netzwerk-Panel des Browsers.

Falsche Sprache​

Prüfen Sie zuerst Anpassen → Erscheinungsbild auf die Spracheinstellungen des Widgets. Der gehostete Widget-Code wählt die Sprache der Benutzeroberfläche in dieser Reihenfolge aus:

  1. data-locale, aber nur wenn Script-Überschreibung erlauben aktiv ist.
  2. Im Modus Festgelegt die konfigurierte Default-Sprache.
  3. Im Modus Automatisch erkennen <html lang>, danach Browser-Sprachkandidaten und schließlich die konfigurierte Default-Sprache.

Nicht unterstützte Locale-Kandidaten werden übersprungen. Englisch ist der letzte Fallback, wenn kein Kandidat unterstützt wird; die konfigurierte Default-Sprache ist anfangs Englisch.

Korrekturen:

  • Wählen Sie für automatische Erkennung Automatisch erkennen und entfernen Sie einen falschen data-locale-Wert oder deaktivieren Sie Script-Overrides.
  • Legen Sie <html lang="de">, <html lang="fr"> oder den entsprechenden Sprachcode auf lokalisierten Seiten fest.
  • Wählen Sie Festgelegt und deaktivieren Sie Script-Überschreibung erlauben, um die konfigurierte Sprache zu erzwingen. Bei erlaubten Script-Overrides hat data-locale weiterhin Vorrang vor dem Modus Festgelegt.
  • Prüfen Sie, ob die Einstellungen gespeichert wurden, initialisieren Sie das installierte Widget neu, damit es Dashboard-Konfigurationsänderungen übernimmt, und testen Sie erneut. Im aktuellen Quellcode kann der gehostete Loader widget.js v16 die produktseitigen Beschriftungen aktualisieren, wenn eine Änderung an <html lang> oder am data-locale des Loaders die aufgelöste Locale ändert. Prüfen Sie die Version des ausgelieferten Loaders, bevor Sie sich auf Live-Aktualisierungen verlassen; dieses Verhalten des gehosteten Loaders ist unabhängig vom veröffentlichten npm-SDK 0.1.4. Ein an mountWidget() übergebenes locale wird zu data-locale und folgt derselben Projektregel.
  • Wenn das Widget nicht verfügbar ist, prüfen Sie die Anfrage /widget-config und den öffentlichen Schlüssel. Im aktuellen Quellcode bleibt das gehostete Widget widget.js v16 bei einem Fehler beim Abruf der Konfiguration nicht verfügbar, statt mit Standardeinstellungen zu starten. Prüfen Sie die Version des ausgelieferten Loaders, bevor Sie sich auf dieses Verhalten verlassen.
  • Indexieren Sie jede benötigte Sprachversion, wenn Antworten Inhalte in der falschen Sprache abrufen oder zitieren. Der Antwortgenerator erkennt die Sprache anhand der Frage, unabhängig von der UI-Locale des Widgets; die festgelegte Widget-Sprache erzwingt weder die Antwortsprache noch übersetzt sie Quellinhalte. Wenn kein benutzerdefiniertes assistant.fallbackMessage konfiguriert ist, verwendet die integrierte Fallback-Nachricht bei fehlendem Inhalt die erkannte Sprache der Frage, sofern sie zuverlässig bestimmt werden kann; ist die Erkennung unsicher, verwendet sie die UI-Sprache des Widgets und greift nur als letzten Ausweg auf Englisch zurück.

Keine Quellenangaben oder schwache Antworten​

ChattyBox verwendet abgerufene Quellinhalte, um Antworten zu generieren. Fehlende Quellenangaben oder schwache Antworten können durch fehlende oder ungeeignete Quellinhalte, Abrufprobleme oder Fehler bei der Generierung entstehen; für sich allein weisen sie nicht auf eine bestimmte Ursache hin. Ein quellengebundener RAG-Chatbot profitiert von klaren abgerufenen Quellinhalten, aber eine Quellenangabe allein bestätigt eine Antwort nicht. Vergleichen Sie jede wichtige Aussage mit der zitierten Seite.

Korrekturen:

  • Stellen Sie die gleiche Frage im Dashboard-Testchat und vergleichen Sie die zitierten Seiten.
  • Stellen Sie sicher, dass die Quellseite öffentlich und im Crawl enthalten ist.
  • Fügen Sie der Quellseite klare Überschriften, Beispiele, FAQs und direkten Antworttext hinzu.
  • Verlassen Sie sich nicht auf Screenshots, Videos, ausgeschlossenes verborgenes Markup, reine JavaScript-Inhalte oder iframes als einzige Quelle.
  • Scrapen Sie die aktualisierte Seite erneut, sobald der Cooldown es erlaubt, warten Sie auf die Embedding-Verarbeitung und testen Sie dann erneut.
  • Prüfen Sie Warnungen Teilweise indexiert: Text jenseits des Limits von 512 KiB pro Seite bleibt nicht erhalten. Teilen Sie lange Quellseiten auf, statt denselben gekürzten Text wiederholt neu aufzubauen.
  • Formulieren Sie Fragen nach Möglichkeit klar und eigenständig. Der Antwortgenerator kann bis zu 12 aktuelle gespeicherte Nachrichten mit jeweils höchstens 2.000 Zeichen erhalten; er erhält nicht das vollständige Unterhaltungstranskript.

Persona ergänzt die integrierten Grounding-Regeln um websitespezifische Anweisungen. Sie kann fehlende indexierte Inhalte nicht bereitstellen und den Fallback bei fehlendem Kontext oder einer Inhaltslücke nicht ersetzen, wenn dieser ausgelöst wird. Der Inhaltslücken-Detektor arbeitet heuristisch und erkennt möglicherweise nicht jede unbelegte Antwort. Dieser Fallback wird separat über assistant.fallbackMessage in der Konfiguration als Code festgelegt.

Nicht gecrawlte Seiten oder veraltete Inhalte​

Häufige Ursachen:

  • Die Seite fehlt in der übermittelten Sitemap.
  • Im manuellen URL-Modus wurde die Seite nicht einbezogen.
  • Die Seite blockiert gewöhnliche HTTP-Abrufe, erfordert eine Authentifizierung, liefert eine CAPTCHA-/Fehlerseite oder leitet zu einem blockierten Ziel weiter.
  • Der Seiteninhalt hat sich nach dem letzten Scraping geändert.
  • Der Inhalt wird nur per JavaScript gerendert oder liegt außerhalb des ausgewählten semantischen Inhaltsbereichs.
  • Die ausgewählten URLs überschreiten das Seitenkontingent, das monatliche Refresh-Budget ist aufgebraucht oder eine Ein-/Ausschlussregel filtert sie heraus.

Korrekturen:

  1. Bestätigen Sie, dass die Seite öffentlich in einem privaten Browserfenster geöffnet wird.
  2. Verwenden Sie den Sitemap-Modus für eine umfassende Abdeckung oder manuelle URLs für eine kuratierte Gruppe.
  3. Senden Sie die kanonische URL anstelle einer Tracking-URL, einer Weiterleitungs-URL oder einer Anmelde-URL.
  4. Scrapen Sie nach Inhaltsänderungen erst wieder, wenn der Cooldown abgelaufen ist: mindestens sieben Tage seit Erstellung des letzten Jobs bei Free oder 24 Stunden bei kostenpflichtigen Tarifen, auch wenn der Job fehlgeschlagen ist.
  5. Öffnen Sie Wissensbasis → Seiten, klappen Sie Importverlauf auf, wenn Aufträge vorhanden sind, und wählen Sie unter Scrape-Jobs einen Auftrag aus. Vergleichen Sie dessen gespeicherte/ausgewählte Seitenzahlen und die Liste Seiten mit den erwarteten URLs. Abgeschlossen kann übersprungene oder fehlgeschlagene URLs enthalten; Mit Warnungen abgeschlossen kennzeichnet ausdrücklich teilweise gespeicherten Seitentext, nicht alle Crawl-Fehler. Die Benutzeroberfläche zeigt keine vollständige Fehlerliste pro URL.

ChattyBox liest robots.txt möglicherweise aus, um Sitemap-Angaben derselben Herkunft zu entdecken, setzt dessen Crawl-Direktiven aber nicht durch. Behandeln Sie robots.txt nicht als Zugriffsschutz. Sichere HTTP-Weiterleitungen werden verfolgt; eine Weiterleitung allein ist daher kein Fehler. Entfernen Sie keine Zugriffsschutzmaßnahmen und stellen Sie private Inhalte nicht öffentlich bereit, damit sie gecrawlt werden können.

Wenn eine URL von der Website oder aus der Quellenauswahl entfernt wurde, kann die gespeicherte Seite weiterhin verwendet werden. Löschen Sie sie zusätzlich unter Wissensbasis → Seiten und schließen Sie sie von zukünftigen Suchläufen aus. Index neu aufbauen verwendet gespeicherten Text und ruft die Website nicht erneut ab; es hat einen eigenen tarifabhängigen Cooldown und verbraucht das monatliche Aktualisierungsbudget.

Einstellungen werden nicht gespeichert​

Änderungen an Chatbot-Details und Quelleinstellungen werden automatisch gespeichert. Prüfen Sie den Speicherstatus, beheben Sie Validierungsfehler oder wiederholen Sie einen fehlgeschlagenen Speicherversuch, bevor Sie fortfahren. Auch bei manueller URL-Eingabe ist eine gespeicherte Website-URL im Dashboard erforderlich. Die Suche und das automatische Speichern starten keinen Import; prüfen Sie die ausgewählten Seiten und starten Sie den Import ausdrücklich.

Bei Config locked muss die Konfiguration über den CLI-Workflow bereitgestellt werden. Die Sperre ist unumkehrbar; Persona-Speicherungen, Scraping-Konfiguration, Scrape Now, das Löschen von Inhalten und Index-Neuaufbauten werden abgelehnt, auch wenn ein Steuerelement noch sichtbar ist. Nur die Branding-Einstellung bleibt im Dashboard für die Konfiguration des gehosteten Widgets änderbar, abhängig vom Tarif. Öffentliche Widget-Schlüssel und Deployment-Tokens sind getrennte Zugangsdaten.

Wenn ein Projekt fehlt oder der Zugriff verweigert wird, prüfen Sie, ob Sie als Eigentümer angemeldet sind. Ein Widget-Schlüssel, Deployment-Token oder die Mitgliedschaft in einer Organisation gewährt keine Dashboard-Eigentümerrechte. Unter Konversationen sind Analysen und Unbeantwortete Fragen in Pro und Business enthalten; bei nicht verfügbaren Ansichten erscheint ein Hinweis auf ein Tarif-Upgrade. Verlauf ist in allen Tarifen verfügbar.

Steckt immer noch fest​

Sammeln Sie diese Daten, bevor Sie den Support kontaktieren:

  • Die URL der öffentlichen Seite, auf der das Widget erscheinen soll.
  • Ein Screenshot oder eine Kopie eines beliebigen Browserkonsolenfehlers.
  • Ob die Seite ein einfaches HTML, Next.js, Docusaurus, WordPress, ein CMS oder Google Tag Manager verwendet.
  • Ob das Snippet data-api-key und data-api-url enthält.
  • Eine Testfrage, die funktionieren sollte, und die Quellseite, die sie beantwortet.