Ga naar de hoofdinhoud

Problemen oplossen

Gebruik deze pagina wanneer de widget is geïnstalleerd, maar niet werkt zoals verwacht.

De widget verschijnt niet​

Controleer eerst de browserconsole. ChattyBox meldt daar wanneer verplichte attributen ontbreken.

Veelvoorkomende oorzaken:

  • Het script ontbreekt zowel in de gedeployde HTML als in de live DOM.
  • Het script is toegevoegd aan de verkeerde template, lay-out, Tag Manager-container of CMS-codeplek.
  • Het script valt onder een toestemmingsregel of Tag Manager-trigger die niet is geactiveerd.
  • De applicatiecomponent die de loader mount, wordt op die route niet uitgevoerd.
  • Een Content Security Policy blokkeert https://chattybox.ai/widget.js.
  • CSS of een andere widget valt over de launcher heen.
  • De gedeployde configuratie bevat widget.enabled: false.

Kleinste oplossing:

  1. Open de gedeployde openbare pagina in een incognitovenster.
  2. Zoek in de paginabron én in het Elements-paneel van de browser naar chattybox.ai/widget.js; een loader die door een SDK of JavaScript wordt ingevoegd, is soms alleen zichtbaar in de live DOM.
  3. Controleer of het script één keer voorkomt en data-api-key en data-api-url bevat.
  4. Ontbreekt het script, plaats het dan in de globale footer, app-lay-out, Docusaurus-root of op de GTM-trigger All Pages.

Bij configuratiegestuurde projecten voorkomt widget.enabled: false dat de gehoste widget wordt geïnitialiseerd en retourneren openbare POST /chat-verzoeken 403 Widget is disabled, ook verzoeken van de headless SDK. Wijzig deze instelling via de configuratiedeploymentworkflow, niet door de openbare sleutel te vervangen. Als de loader na initialisatie wordt verwijderd, verdwijnt de al weergegeven widget niet.

data-api-url ontbreekt​

De widget stopt direct als data-api-url ontbreekt.

Gebruik het volledige fragment uit het dashboard of voeg het verplichte attribuut toe:

<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>

Gebruik de API-URL uit je dashboard in plaats van er zelf een te raden. In productie hoort dit een stabiele https://...convex.site/chat-URL te zijn.

Generieke fout 401 Invalid API key​

Om veiligheidsredenen geven widget-API-endpoints dezelfde generieke reactie 401 Invalid API key voor een onbekende, verlopen of op basis van de origin geweigerde openbare sleutel. Gebruik de reactie niet om de oorzaak vast te stellen.

Veelvoorkomende oorzaken:

  • De openbare widgetsleutel is verkeerd gekopieerd.
  • De sleutel is verwijderd, verlopen of afkomstig van een andere backenddeployment dan de API-URL.
  • Het project of de eigenaar van de sleutel wordt verwijderd.
  • De optionele originbeperking is ingeschakeld voor de sleutel en de huidige site-origin ontbreekt.

Oplossingen:

  1. Open het project in het ChattyBox-dashboard.
  2. Open Installeren → Installatie op website, voer de website-URL in en kopieer onder Embedcode een geschikt fragment als dat beschikbaar is.
  3. Kies onder Sleutels en domeinen op dezelfde pagina Origins bewerken voor de sleutel in het geïnstalleerde fragment. Als Deze sleutel beperken tot specifieke origins is ingeschakeld, voeg dan de exacte origin toe waarop de pagina wordt aangeboden of schakel de optionele beperking uit. Schema, hostnaam en poort moeten overeenkomen: https://example.com, https://preview.example.com en http://localhost:3000 zijn verschillende origins. Paden hoeven niet afzonderlijk te worden toegevoegd.
  4. Deploy of publiceer de site opnieuw en test weer in een incognitovenster.

Een geldige sleutel voor een andere chatbot op dezelfde backend selecteert normaal gesproken die chatbot in plaats van een 401 te geven; controleer het project als antwoorden onverwacht zijn. Sleutelnamen zoals "production" en "staging" dwingen geen omgevingen af. De HTTP-API gebruikt Origin wanneer die header aanwezig is; alleen als die ontbreekt, gebruikt de API de origin van Referer. Een beperkte sleutel weigert het verzoek als de gekozen origin ontbreekt, ongeldig is of niet is toegestaan. Een toegestane Referer kan een niet-toegestane Origin niet overrulen. Originbeperkingen vervangen geen bezoekersauthenticatie.

Berichtlimieten of snelheidslimieten​

Controleer Account en facturatie op /settings/account voor berichtgebruik, je abonnement en eventuele PAYG-budgetten voor Pro/Business. Chatbot testen en openbare chat gebruiken allebei de gedeelde berichtlimiet van de eigenaar. Gesprekken verwijderen of een andere sleutel aanmaken reset die limiet niet.

Fouten door de maandlimiet en kortetermijnlimieten voor verzoeken zijn verschillend. Respecteer bij HTTP-reacties 429 de header Retry-After als die wordt meegestuurd, in plaats van steeds opnieuw te proberen. Wacht bij een fout vanwege de maandelijkse berichtlimiet tot de limiet wordt gereset of pas het abonnement of het in aanmerking komende PAYG-budget aan. De pagina Gesprekken → Geschiedenis toont gesprekken, geen foutenconsole per verzoek; bekijk HTTP-fouten in het Network-paneel van de browser.

Verkeerde taal​

Controleer eerst de taalinstellingen van de widget onder Aanpassen → Uiterlijk. De gehoste widget in de huidige broncode kiest de UI-taal in deze volgorde:

  1. data-locale op het widgetscript, alleen als Script-override toestaan is ingeschakeld.
  2. In de modus Vast de ingestelde standaardtaal.
  3. In de modus Automatisch detecteren de waarde van <html lang>, daarna de browsertaalkandidaten en ten slotte de ingestelde standaardtaal.

Niet-ondersteunde kandidaten worden overgeslagen. Engels is de laatste terugvaloptie als geen kandidaat wordt ondersteund; de standaardtaal is aanvankelijk Engels.

Oplossingen:

  • Kies voor automatische taalselectie Automatisch detecteren en verwijder een onjuiste data-locale of schakel Script-override toestaan uit.
  • Stel op gelokaliseerde pagina's <html lang="de">, <html lang="fr"> of de bijbehorende ondersteunde taalcode in.
  • Kies Vast en schakel Script-override toestaan uit om de ingestelde taal af te dwingen. Als overschrijvingen zijn ingeschakeld, krijgt data-locale ook in de modus Vast voorrang.
  • Controleer of de instellingen zijn opgeslagen, initialiseer de geïnstalleerde widget opnieuw om dashboardwijzigingen op te halen en test nogmaals. De gehoste widget.js v16 uit de huidige broncode kan producteigen labels bijwerken wanneer een wijziging aan <html lang> of de data-locale van de loader de opgeloste locale verandert. Controleer de gedeployde loaderversie voordat je op live updates vertrouwt; dit gedrag van de gehoste loader staat los van de gepubliceerde npm-SDK 0.1.4. Door de projecteigenaar aangepaste titels en welkomstberichten worden weergegeven zoals ingevoerd en niet automatisch vertaald. Een locale die aan mountWidget() wordt doorgegeven, wordt data-locale en volgt hetzelfde projectbeleid.
  • Controleer het verzoek /widget-config en de publieke sleutel als de widget niet beschikbaar is. Bij de gehoste widget.js v16 uit de huidige broncode blijft de widget na een mislukte config-fetch onbeschikbaar; de loader start hem niet met standaardwaarden. Controleer welke loaderversie is gedeployed.
  • Indexeer elke benodigde taalversie als antwoorden content in de verkeerde taal citeren of ophalen. De antwoordgenerator leidt de taal af uit de vraag, los van de UI-locale van de widget: de taalinstelling Vast dwingt de antwoordtaal niet af en vertaalt de broncontent niet. Als geen aangepaste assistant.fallbackMessage is ingesteld, gebruikt de ingebouwde terugvalmelding voor ontbrekende content waar passend de gedetecteerde vraagtaal; als die onzeker is, gebruikt de melding de UI-taal van de widget, met Engels als laatste terugvaloptie.

Geen citaten of zwakke antwoorden​

ChattyBox gebruikt opgehaalde broncontent om antwoorden te genereren. Ontbrekende citaten of zwakke antwoorden kunnen het gevolg zijn van ontbrekende of ongeschikte broncontent, problemen bij het ophalen of generatiefouten; op zichzelf wijzen ze niet op een specifieke oorzaak.

Een op bronnen gebaseerde RAG-chatbot heeft baat bij duidelijke opgehaalde broncontent, maar een citaat alleen verifieert een antwoord niet. Vergelijk elke belangrijke bewering met de geciteerde pagina.

Oplossingen:

  • Stel dezelfde vraag in de testchat van het dashboard en vergelijk de geciteerde pagina's.
  • Zorg ervoor dat de bronpagina openbaar is en in de crawl is opgenomen.
  • Voeg duidelijke koppen, voorbeelden, FAQ's en directe antwoorden toe aan de bronpagina.
  • Vertrouw niet uitsluitend op screenshots, video's, uitgesloten verborgen markup, content die alleen via JavaScript beschikbaar is of iframes.
  • Scrape de bijgewerkte pagina opnieuw zodra de cooldown dit toestaat, wacht tot het embedden is voltooid en test opnieuw.
  • Controleer op waarschuwingen Gedeeltelijk geïndexeerd: tekst boven de limiet van 512 KiB per pagina wordt niet bewaard. Splits lange bronpagina's op in plaats van steeds dezelfde afgekorte tekst opnieuw op te bouwen.
  • Maak vragen waar mogelijk duidelijk en zelfstandig. De antwoordgenerator kan maximaal 12 recente opgeslagen berichten ontvangen, elk met een limiet van 2.000 tekens; de volledige gesprekstranscriptie wordt niet meegestuurd.

Persona voegt sitespecifieke instructies toe aan de ingebouwde groundingregels; Persona kan ontbrekende geïndexeerde content niet leveren en vervangt de terugval voor ontbrekende context of contentgaten niet wanneer die wordt geactiveerd. De contentgatendetector werkt heuristisch en herkent mogelijk niet elk niet-onderbouwd antwoord. Die terugvalmelding heeft een afzonderlijke instelling, assistant.fallbackMessage, in configuration as code.

Pagina's worden niet gescrapet of bevatten verouderde content​

Veelvoorkomende oorzaken:

  • De pagina ontbreekt in de ingediende sitemap.
  • De handmatige URL-modus bevatte de pagina niet.
  • De pagina blokkeert gewone HTTP-verzoeken, vereist authenticatie, retourneert een CAPTCHA- of foutpagina of verwijst door naar een geblokkeerd doel.
  • De pagina-inhoud is gewijzigd na de laatste scrape.
  • De content wordt alleen met JavaScript weergegeven of valt buiten de geselecteerde semantische content-root.
  • De geselecteerde URL's overschrijden de paginalimiet, het maandelijkse verversingsbudget is op of een include-/exclude-regel heeft ze gefilterd.

Oplossingen:

  1. Controleer of de pagina openbaar toegankelijk is in een privévenster van de browser.
  2. Gebruik de sitemapmodus voor brede dekking of handmatige URL's voor een samengestelde selectie.
  3. Dien de canonieke URL in, niet een tracking-URL, redirect-URL of ingelogde URL.
  4. Scrape opnieuw nadat de content is gepubliceerd en de cooldown is verstreken: minimaal zeven dagen sinds de laatste taak is aangemaakt op Free, of 24 uur op betaalde abonnementen, ook als die taak is mislukt.
  5. Klap in Kennis → Pagina’s Importgeschiedenis uit wanneer er taken zijn en selecteer een taak onder Scrapejobs. Vergelijk de opgeslagen/geselecteerde aantallen van de taak en de lijst Pagina’s met de bedoelde URL's. Voltooid kan overgeslagen of mislukte URL's bevatten; Voltooid met waarschuwingen duidt specifiek op gedeeltelijk bewaarde paginatekst, niet op alle crawlproblemen. De UI biedt geen volledige lijst met fouten per URL.

ChattyBox handhaaft de crawlinstructies van robots.txt niet, maar kan het bestand lezen om sitemapvermeldingen te vinden. Behandel robots.txt niet als toegangsbeheer. ChattyBox volgt veilige HTTP-redirects; een redirect is dus op zichzelf geen fout. Verwijder geen toegangsbeveiliging en zet geen privécontent op een openbare URL om deze crawlbaar te maken.

Als een URL van de site of uit de bronselectie is verwijderd, kan de opgeslagen pagina nog steeds worden gebruikt. Verwijder de pagina ook onder Kennis → Pagina’s en sluit deze uit van toekomstige ontdekking. Index opnieuw opbouwen gebruikt opgeslagen tekst en haalt de pagina niet opnieuw op via het netwerk; het heeft een eigen cooldown per abonnement en verbruikt bovendien het maandelijkse verversingsbudget.

Instellingen worden niet opgeslagen​

Wijzigingen aan chatbotgegevens en broninstellingen worden automatisch opgeslagen. Controleer de opslagstatus, los validatiefouten op of probeer een mislukte opslag opnieuw voordat je verdergaat. Het dashboard vereist een opgeslagen Website URL, ook wanneer je handmatige URL's invoert. Ontdekking en automatisch opslaan starten geen import; controleer de geselecteerde pagina's en start de import expliciet.

Als het project Configuratie vergrendeld is, moet de configuratie worden gedeployed via de CLI-workflow. De vergrendeling is onomkeerbaar; Persona opslaan, scrapeconfiguratie wijzigen, Nu scrapen, content verwijderen en de index opnieuw opbouwen worden geweigerd, ook als de betreffende bedieningselementen nog zichtbaar zijn. Alleen de brandingvoorkeur kan binnen de configuratie van de gehoste widget nog via het dashboard worden gewijzigd, afhankelijk van het abonnement. Openbare widgetsleutels en deploymenttokens zijn afzonderlijke gegevens.

Als een project ontbreekt of toegang wordt geweigerd, controleer dan of je bent aangemeld als eigenaar. Een widgetsleutel, deploymenttoken of lidmaatschap van een organisatie geeft geen dashboardrechten als eigenaar. Onder Gesprekken zijn Analyses en Onbeantwoorde vragen inbegrepen bij Pro en Business; niet-beschikbare weergaven tonen een upgradeprompt. Geschiedenis is beschikbaar in alle abonnementen.

Nog steeds vast?​

Verzamel deze gegevens voordat je contact opneemt met support:

  • De openbare pagina-URL waarop de widget moet verschijnen.
  • Een screenshot of kopie van een fout in de browserconsole.
  • Of de pagina gewone HTML, Next.js, Docusaurus, WordPress, een CMS of Google Tag Manager gebruikt.
  • Of het fragment data-api-key en data-api-url bevat.
  • Eén testvraag die zou moeten werken en de bronpagina die deze beantwoordt.