:::note Broncode en versies
In de huidige checkout is de broncode van de gehoste loader widget.js v16; dit vertelt niet welke versie je site laadt. Controleer de daadwerkelijk geleverde loader voordat je vertrouwt op gedrag uit de huidige broncode. De gepubliceerde npm-SDK 0.1.4 deelt identieke mounts: roep remove() aan op elke bijbehorende handle; alleen de laatste start de teardown. Headless sendMessage() probeert niet automatisch opnieuw.
:::
De gehoste widget aanpassen
Pas de kant-en-klare interface aan die wordt geladen door https://chattybox.ai/widget.js. Zie Installatiehandleidingen voor canonieke installatievoorbeelden voor frameworks en platforms.
Voordat je aanpast
Maak het project, indexeer de content en controleer representatieve antwoorden met Chatbot testen voordat je tijd besteedt aan de presentatie. Zie Aan de slag voor de volledige volgorde.
De gehoste widget configureren
- Ga naar je Dashboard en selecteer je project.
- Open Aanpassen → Uiterlijk om het uiterlijk, de branding en de instellingen voor Taal te bewerken.
- Controleer de relevante status van automatisch opslaan; los validatiefouten op of probeer mislukte saves opnieuw voordat je de geïnstalleerde widget test.
Installatiecode en publieke sleutels worden beheerd onder Installeren. Als je klaar bent om te installeren:
- Open Installeren → Sleutels en domeinen → Publieke sleutels om een publieke browsersleutel te controleren of te maken en de origininstellingen te bekijken. Gebruik zo nodig Origins bewerken.
- Voer onder Installeren → Installatie op website een HTTP(S)-website-URL in, kies een geschikte sleutel en kopieer het gegenereerde fragment. De kiezer toont niet-verlopen sleutels die onbeperkt zijn of voor de origin van die URL zijn toegestaan. Een sleutel zonder beperkingen werkt vanaf alle origins; een sleutel die voor een website is klaargezet, kan al tot de origin van die site zijn beperkt. Controleer de geselecteerde sleutel voordat je die voor staging of localhost gebruikt.
- Je kunt exacte originbeperkingen inschakelen als extra beveiliging; ze authenticeren geen bezoekers.
- Volg de Installatiehandleidingen voor je platform.
<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>
Opgeslagen wijzigingen aan de widgetpresentatie worden bij de volgende initialisatie toegepast; je hoeft het fragment op je site niet te vervangen. Reeds geopende pagina’s worden niet live bijgewerkt: laad ze opnieuw om de opgeslagen instellingen op te halen.
In de huidige broncode blijft de widget onbeschikbaar en wordt er geen fallbackinterface weergegeven als het ophalen van de configuratie mislukt of de respons ongeldig is. Ook een geldige configuratierespons met enabled: false houdt de widget onbeschikbaar; de chat-API weigert verzoeken met HTTP 403 wanneer de widget is uitgeschakeld, ook SDK-verzoeken. Dit is iets anders dan een mislukte configuratieophaling. Als de configuratie wel succesvol is opgehaald maar het laden van vertalingen mislukt, kan de widget starten met de ingebouwde Engelse labels. Controleer de geleverde loader voordat je op dit gedrag uit de huidige broncode vertrouwt.
Visuele aanpassing
In de sectie Widgetuiterlijk van de dashboardeditor kun je ondersteunde widgetkleuren, positie, pictogram en tekst aanpassen zonder de code van je site te wijzigen. Controleer het resultaat in de gehoste widget, want de preview en loader zijn niet identiek.
Dashboardinstellingen
-
Accentkleur - Kies de primaire merkkleur. Dit beïnvloedt de openingsknop, belangrijke accenten en gebruikersberichten.
-
Widgetpositie - Kies waar de widget op het scherm verschijnt.
-
Koptitel - Stel de titel bovenaan het chatvenster in.
-
Welkomstbericht - Pas het eerste bericht aan dat bezoekers zien wanneer ze de chat openen.
-
ChattyBox-branding tonen - Bij het abonnement Gratis is branding verplicht. Met Starter en hogere abonnementen kun je de footervermelding verbergen.
De editor heeft ook de instellingen Widgetachtergrond, Tekstkleur en Widgetpictogram. De pictogramopties zijn Standaard, Emoji, Afbeeldings-URL en Uploaden; de instelling Pictogramgrootte verschijnt alleen bij Afbeeldings-URL of Uploaden en biedt klein, middel of groot. Geüploade pictogrammen mogen maximaal 512 KiB groot zijn en moeten een geaccepteerd MIME-type voor afbeeldingen hebben (PNG, JPEG, WebP, SVG, GIF of ICO). De broncode van de huidige gehoste loader v16 gebruikt iconSize om de openingsknop en het pictogram te dimensioneren; controleer de geleverde loader voordat je op dit gedrag vertrouwt.
Controleer de relevante status van automatisch opslaan en laad daarna de geïnstalleerde pagina opnieuw om wijzigingen te verifiëren. De dashboardpreview is een mock-up, niet de gehoste widget zelf. Bij projecten die met config-as-code zijn vergrendeld, worden uiterlijk en taal via de configuratie beheerd; projecten met de juiste rechten kunnen de brandingvoorkeur nog wel apart opslaan.
Standaardconfiguratie
Dit zijn de standaardwaarden die een geslaagde aanvraag voor de openbare widgetconfiguratie teruggeeft wanneer er geen aangepaste waarde is:
| Veld | Standaardwaarde |
|---|---|
enabled | true, tenzij uitgeschakeld voor het project |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; alle vier de hoeken worden ondersteund |
iconType, iconSize | default, medium; de gehoste loader v16 uit de huidige broncode gebruikt de grootte voor de openingsknop en het pictogram |
iconEmoji, iconUrl | Tekstballon-emoji, null |
headerTitle | Chat with us (standaardwaarde van de API) |
welcomeMessage | Hi! 👋 How can I help you today? (standaardwaarde van de API) |
showBranding | true; verplicht ingeschakeld voor Free-projecten |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (standaardwaarden) |
Bij het mounten deelt de gepubliceerde SDK 0.1.4 alleen identieke opties. Een gewijzigde sleutel, endpoint, script-URL, locale of debuginstelling wordt geweigerd totdat alle bijbehorende handles zijn verwijderd.
Geavanceerde opties
Dashboardinstellingen versus scriptattributen
Beheer het meeste widgetgedrag vanuit het dashboard, zodat je je website niet opnieuw hoeft te deployen voor eenvoudige wijzigingen.
Gebruik het dashboard voor kleuren, positie, pictogram, titel, welkomstbericht, taalinstellingen, beheer van publieke sleutels, scraping en analyses.
Publieke sleutels zijn bedoeld voor gebruik in browsercode: ze identificeren het project, maar zijn geen beheergegevens en authenticeren geen bezoekers. Een sleutel die zonder beperkingen is aangemaakt, werkt in productie, previews, staging en localhost; een voor een website voorbereide sleutel kan al tot die origin zijn beperkt. Originbeperkingen zijn optioneel en bieden extra beveiliging; houd de exacte origins gesynchroniseerd met de domeinen waarop de widget is geïnstalleerd als je ze inschakelt.
Gebruik scriptattributen om de widget bij initialisatie te configureren:
data-api-keyidentificeert de openbare widgetsleutel.data-api-urlvertelt de widget waar verzoeken naartoe moeten. In productie is dit een stabielehttps://...convex.site/chat-URL uit je dashboard.data-localevraagt bij initialisatie om een specifieke widget-UI-taal als het project script-overrides toestaat. In de huidige broncode volgt de loader ook latere wijzigingen aan dit attribuut.data-colorendata-positionoverschrijven de opgeslagen accentkleur en positie, maar alleen nadat de configuratie succesvol is opgehaald. Gebruik bij voorkeur dashboardinstellingen; deze attributen kunnen latere dashboardwijzigingen verhullen.data-debug="true"schakelt browserdiagnostiek in; standaard staat dit uit.
Bij elk nieuw bericht probeert de gehoste widget uit de huidige broncode de origin en het pad van de huidige HTTP(S)-pagina mee te sturen voor Populaire triggers, zonder te controleren of de pagina openbaar is. Ongeldige of te lange context wordt weggelaten; retries gebruiken de oorspronkelijke context opnieuw. Querystrings, fragmenten en inloggegevens worden verwijderd, maar paden kunnen gevoelige identificatiegegevens bevatten. De widget respecteert ook prefers-reduced-motion, biedt een gelabeld berichtveld en live aankondigingen, en toont citaties in een toetsenbordtoegankelijke uitklapsectie Bronnen.
De pagina-context komt van de huidige HTTP(S)-URL, niet van een controle of de pagina openbaar is. Laad de widget niet op gevoelige routes alleen omdat querystrings worden verwijderd. De loader kan ook initialisatie-, configuratie-, vertaal- en chatfouten naar /widget-error sturen via een beacon of fetch, met begrensde foutdetails, locale, versie en de origin/het pad van de pagina. Debugmodus is niet nodig voor deze rapporten.
Chat gebruikt volledige JSON-responsen, geen tokenstreaming. De broncode van de huidige gehoste loader v16 maakt per bericht een idempotentiesleutel en plant maximaal 10 automatische transportpogingen voor netwerkfouten, onderbroken succesvolle responsbody’s, HTTP 429, HTTP 5xx en 409-responsen met een leesbare Retry-After-header. Er wordt geen nieuwe poging gepland als de wachttijd het budget van 30 seconden zou overschrijden; dit is geen harde timeout voor een verzoek dat al bezig is. Browser-CORS kan Retry-After verbergen. Headless sendMessage() biedt deze retry niet; de startup-GET-verzoeken van de loader hebben afzonderlijke retries. Voor het ophalen van de configuratie probeert loader v16 eerst Authorization: Bearer en alleen na HTTP 400 een nieuwe aanvraag met de sleutel in de querystring. Als window.ChattyboxSDK de constructor Chattybox beschikbaar stelt, gebruikt de loader de gepubliceerde npm-SDK 0.1.4 voor het ophalen van de configuratie; ook daar geldt de querystringfallback alleen voor configuratie. Het versturen van chatberichten gebruikt het eigen transport van de loader. De gespreksstatus blijft in het geheugen van die widgetinstantie en gaat verloren bij herladen of herinitialiseren; opgeslagen serverberichten kunnen blijven bestaan. Bronnen worden ontdubbeld en beperkt tot drie weergegeven vermeldingen; fallbackantwoorden kunnen geen bronnen hebben. Controleer de geleverde loader voordat je op gedrag uit de huidige broncode vertrouwt.
Verschijnt de widget na installatie niet, bekijk dan Probleemoplossing.
Begin voor platformspecifieke voorbeelden met Docusaurus, MkDocs, VitePress, WordPress of GitBook.
De widget op specifieke pagina’s verbergen
Gebruik de volgende CSS om de widget alleen op geselecteerde pagina’s visueel te verbergen (als je dit overal toepast, wordt de widget overal verborgen):
.chattybox-widget {
display: none;
}
Verbergen met CSS stopt de initialisatie, API-verzoeken of foutmeldingen niet en is geen toestemmings- of privacymaatregel. De loader beslist niet over toestemming: voeg het script pas in nadat de vereiste toestemming is gegeven en voorkom opnieuw invoegen na intrekking of op uitgesloten routes. Voor client-side routewisselingen of het intrekken van toestemming biedt de broncode van widget.js v16 window.ChattyBox.destroy(). Verwijder bij SDK 0.1.4 alle bijbehorende mount-handles; de laatste geeft het teardown-signaal. Controleer of de geleverde loader teardown ondersteunt; alleen de script-tag verwijderen is niet genoeg. Teardown verwijdert eigen UI en stijlen en annuleert werk dat nog bezig is, maar kan verzoeken die de server al heeft verwerkt niet ongedaan maken.
Browserbediening
In de broncode van widget.js v16 bestaat window.ChattyBox al tijdens het laden, met status: 'loading' en destroy(). Controleer na een geslaagde initialisatie window.ChattyBox?.status === 'ready' voordat je open(), close(), toggle() of sendMessage(text) aanroept. destroy() verwijdert de eigen widget en stijlen, stopt het werk van de instantie en verwijdert het globale object; reeds door de server verwerkte verzoeken kunnen niet ongedaan worden gemaakt. close() sluit alleen het chatvenster; de openingsknop blijft staan. sendMessage(text) geeft een promise voor de UI-bewerking terug, niet voor het antwoord; nieuwe berichten worden genegeerd zolang een ander bericht wordt verwerkt. Dit globale object is iets anders dan de SDK-constructors op window.ChattyboxSDK. Controleer de geleverde loader voordat je op dit gedrag vertrouwt.
Door de site beheerde lichte/donkere thema’s (huidige broncode)
De config-as-code-workflow in de huidige broncode ondersteunt optionele paletten in widget.theme.light en widget.theme.dark. Elk palet accepteert primaryColor, backgroundColor en textColor als hexkleuren van zes cijfers; weggelaten kleuren erven de basiswaarden uit widget.theme. Bestaande configuraties met één thema blijven ongewijzigd werken. Hiervoor zijn de CLI/backend uit de huidige broncode en de gehoste loader v16 vereist; de gepubliceerde CLI/config 0.3.1 accepteert deze nieuwe velden niet. Controleer de geleverde loader voordat je op dit gedrag vertrouwt.
Stel data-theme="light" of data-theme="dark" in op het loaderscript voordat het wordt uitgevoerd om het initiële palet te kiezen. Koppel daarna de schakelaar van je site aan de browser-API:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
De widget werkt de bestaande stijlen bij zonder berichten, bronnen, concepttekst of een lopend verzoek te resetten. Met de themakeuze kun je de widget niet uitschakelen of de naamsvermelding verwijderen. Je site beheert het opslaan van voorkeuren en de OS-themavoorkeur; de widget selecteert alleen het geconfigureerde palet.
Aangepaste integraties
Heb je een specifiekere inrichting nodig dan de gehoste widget? Bouw je eigen interface met de JavaScript-SDK of neem contact op met support@chattybox.ai voor architectuuradvies.
Meertalige ondersteuning
In de lokale broncode van widget.js v16 bepaalt de gehoste loader de UI-locale volgens de vaste of automatische projectmodus en volgt hij wijzigingen aan <html lang> en data-locale van het script. De labels worden bijgewerkt zonder het gesprek, het conceptbericht of een openstaande retry te resetten. Alleen navigeren wijzigt de taal niet: pas zo nodig een van deze attributen aan. Dashboardwijzigingen vereisen nog steeds een nieuwe initialisatie. Controleer de geleverde loader voordat je op live taalupdates vertrouwt.
Officieel ondersteunde talen
De widget heeft vertaalcatalogi voor 14 talen. Alle huidige catalogi gebruiken een links-naar-rechtsindeling. Projectteksten en door AI gegenereerde antwoorden worden niet door de UI-catalogi vertaald.
| Taal | Code |
|---|---|
| Engels | en |
| Frans | fr |
| Duits | de |
| Spaans | es |
| Italiaans | it |
| Nederlands | nl |
| Portugees | pt |
| Pools | pl |
| Zweeds | sv |
| Indonesisch | id |
| Ests | et |
| Fins | fi |
| Welsh | cy |
| Tsjechisch | cs |
:::note UI-taal en antwoorden De loader uit de huidige broncode stuurt de opgeloste UI-locale mee met chatverzoeken. De backend detecteert de taal van de vraag en probeert taalbewuste retrieval en generatie. Voor producteigen fallbackberichten heeft een herkend taalsignaal in de vraag voorrang op de UI-locale. Als de taaldetectie geen uitsluitsel geeft of alleen op de ASCII-Engelse heuristiek berust, kan de UI-locale de taal van de fallback bepalen. Zonder een van beide gelden de productstandaarden. Een door het project geschreven fallbackbericht wordt ongewijzigd gebruikt; de UI-locale vertaalt die tekst niet en verandert geen door AI gegenereerde antwoorden. De antwoordkwaliteit en beschikbare talen hangen af van geïndexeerde inhoud en het ingestelde model; de UI-catalogi bieden geen garantie voor de antwoordkwaliteit. :::
Hoe taaldetectie werkt
In de huidige broncode gebruikt de widget de volgende cascade voor taaldetectie:
- Toegestane script-override - een ondersteunde
data-localeheeft voorrang alsallowLocaleOverrideniet false is, ook in de Fixed-modus. - Fixed-modus - zonder een ondersteunde, toegestane override gebruikt de widget
defaultLocaleen negeert hij de pagina- en browsertaal. - Auto-modus - probeer de eerste ondersteunde waarde in deze volgorde:
<html lang>van de pagina,navigator.language, elke waarde innavigator.languages, het verouderdeuserLanguageen ten slottedefaultLocale. - Normalisatie - hoofdletters en kleine letters maken geen verschil; herkende regionale varianten zoals
fr-CAworden teruggebracht tot de ondersteunde basistaal. Niet-ondersteunde kandidaten worden overgeslagen. Als geen enkele kandidaat wordt ondersteund, wordt Engels gebruikt. De standaardinstellingen zijn Auto-modus, Engels en toegestane script-overrides.
Aangepaste kopteksten en welkomstberichten worden letterlijk weergegeven, zonder automatische vertaling. In de huidige broncode zijn de standaardkopteksten en welkomstberichten gelokaliseerd. Als de configuratie is opgehaald maar het laden van vertalingen mislukt, start de widget met de ingebouwde Engelse labels. Als het ophalen van de configuratie mislukt, blijft de widget onbeschikbaar. Controleer de geleverde loader voordat je op dit gedrag vertrouwt.
Taal handmatig overschrijven
Schakel eerst Script-override toestaan in en voeg een ondersteunde data-locale toe aan het loaderscript om een specifieke taal aan te vragen:
<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 Gebruikssituatie
Dit is vooral nuttig als je een meertalige website hebt waarbij elke taalversie een eigen URL heeft (bijvoorbeeld /de/, /fr/). Stel data-locale in op de taal van elke pagina en controleer de gerenderde interface.
:::
Taalinstellingen in het dashboard
In het app-dashboard kun je de taalvoorkeuren van de widget per project configureren:
- Automatisch detecteren - gebruikt eerst de paginataal, daarna de browsertaal en vervolgens de ingestelde standaardtaal, tenzij een toegestane script-override voorrang krijgt
- Vast - gebruikt de geselecteerde interfacetaal, tenzij Script-override toestaan is ingeschakeld en
data-localeis opgegeven - Script-override toestaan - staat toe dat het attribuut
data-localedeze instelling overschrijft
Je vindt deze instellingen in je Dashboard → Aanpassen → Uiterlijk → sectie Taal. Controleer de autosavestatus voor taal en los fouten op of probeer opnieuw op te slaan voordat je test.
Inhoudstaal laten overeenkomen
Indexeer voor een bruikbare meertalige ervaring openbare content in de talen van je bezoekers en test de bronnen; detectie en retrieval zijn niet gegarandeerd. Zo doe je dat:
- Scrape alle taalversies van je documentatie met het bestand
sitemap.xml - De scraper probeert de taal te herkennen; inspecteer inhoud en citaten in plaats van een exact resultaat te veronderstellen
- Retrieval probeert de herkende vraagtaal te verkiezen, maar kan terugvallen op andere geïndexeerde inhoud
Instellen in het app-dashboard: gebruik bij het configureren van scraping de URL van je sitemap.xml (bijvoorbeeld https://yourdocs.com/sitemap.xml) om taalversies te ontdekken en controleer vervolgens de geïndexeerde pagina's. Sitemaps omzeilen crawl-limieten of uitsluitingen niet.
Probleemoplossing
De widget blijft Engels tonen
- Hard refresh als diagnose - Laad opnieuw met Ctrl+F5 of Cmd+Shift+R en controleer daarna in het browsernetwerkpaneel de widget- en vertaalverzoeken
- Controleer
data-locale- Controleer of het attribuut correct is ingesteld met een ondersteunde taalcode - Controleer modus en override-toestemming - De Fixed-modus of uitgeschakelde overrides kunnen de browsertaal of
data-localebewust negeren - Controleer de browsertaal - Controleer of de voorkeurstaal van je browser correct is ingesteld
- Controleer HTML lang van de pagina - Zorg dat je pagina
<html lang="de">(of de juiste code) bevat
Bronnen staan in de verkeerde taal
- Scrape je content opnieuw - Zorg dat alle taalversies zijn geïndexeerd
- Gebruik sitemap.xml - Controleer of de gewenste URL's echt zijn geïndexeerd; crawl-limieten en uitsluitingen kunnen ze weglaten
- Controleer de vraagtaal - De AI probeert de antwoordtaal af te stemmen op de vraagtaal
Ontbrekende vertalingen
- Controleer ondersteunde talen - Alleen de 14 bovenstaande codes hebben catalogi; ontbrekende labels kunnen op Engels terugvallen
Aanbevolen werkwijzen
- Stel
<html lang>in op je pagina’s - Dit helpt bij toegankelijkheid en widgetdetectie - Test tijdens ontwikkeling met
data-locale- Controleer of elke taal correct wordt weergegeven - Scrape alle taalversies - Gebruik
sitemap.xmlvoor ontdekking en controleer de geïndexeerde pagina's - Beoordeel echte vragen - Het dashboard heeft geen rapport voor de verdeling van widget-locales