Ga naar de hoofdinhoud

JavaScript-SDK

:::note Versiestatus De gepubliceerde npm-SDK 0.1.4 valideert baseUrl, verpakt onleesbare response-bodies en probeert config-HTTP-400 slechts eenmaal opnieuw. Met widget.js v15 ondersteunen remove()/window.ChattyBox.destroy() teardown; headless sendMessage() probeert niet automatisch opnieuw. :::

Het npm-pakket is de aanbevolen manier om ChattyBox vanuit applicatiecode te integreren. Configureer de openbare sleutel en API-URL en laad de onderhouden zwevende widget vanuit een blijvende browserlayout, of gebruik de headlessmethoden met je eigen componenten. Volledige widget-teardown vereist ook een bijgewerkte onderhouden widget.js; bij self-hosting moet je dat bestand afzonderlijk bijwerken.

Snel aan de slag​

bun add @openstaticfish/chattybox
import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Houd deze loader gedurende de hele paginale levensduur.

Roep mountWidget() in de browser aan nadat document.body bestaat, niet tijdens rendering of uitvoering op de server. Gebruik een persistente shell. De methode voegt een zwevende widget toe onder document.body, niet in je component. Je kunt { locale: 'fr' } meegeven om bij initialisatie Frans aan te vragen als het project script-overrides toestaat.

De namen import.meta.env.PUBLIC_* in de voorbeelden zijn illustratief. Gebruik de publieke configuratieconventie van je framework, zoals import.meta.env.VITE_* in Vite of process.env.NEXT_PUBLIC_* in Next.js; lees en valideer in Node.js de waarden van process.env.

Je openbare configuratie ophalen​

  1. Maak een project en indexeer je content.
  2. Test representatieve vragen via Chatbot testen.
  3. Controleer of maak een openbare browsersleutel via Installeren → Sleutels en domeinen en bekijk de origininstellingen. Sleutels zonder beperkingen werken op meerdere origins; een voor een website voorbereide sleutel kan al beperkt zijn.
  4. Voer bij Installeren → Installatie op website een HTTP(S)-website-URL in, kies een geschikte sleutel en kopieer de widget-API-URL uit het gegenereerde fragment. De kiezer toont niet-verlopen sleutels die onbeperkt zijn of voor de origin van die URL zijn toegestaan. Voer voor een beperkte sleutel een toegestane origin in en bekijk de beperkingen via Sleutels en toegestane domeinen beheren. Is het formulier niet beschikbaar, voltooi dan eerst de getoonde installatiestap in het dashboard.

Openbare sleutels zijn bedoeld voor browsercode, niet als beheerdersreferenties. Via Installeren → Sleutels en domeinen → Origins bewerken kun je optioneel toegestane origins instellen. Een beperking vergelijkt het genormaliseerde protocol, de hostnaam en de poort exact, niet paden of wildcard-subdomeinen. De API gebruikt Origin of, als die ontbreekt, de origin van Referer. Bij een beperkte sleutel geeft een ontbrekende of niet-toegestane origin HTTP 401 Invalid API key, net als een ongeldige of verlopen sleutel. Node.js-fetch stuurt deze browserheaders niet automatisch mee. Origincontroles zijn geen authenticatie en voorkomen niet dat een niet-browserclient headers vervalst. Het ESM-pakket werkt in Node.js en browsers met fetch.

Constructor en exports​

new Chattybox(options) accepteert een verplichte, niet-lege openbare apiKey, een verplichte baseUrl en een optionele fetch-compatibele fetch-functie; anders wordt de globale fetch gebruikt. SDK 0.1.4 vereist voor baseUrl een absolute HTTP(S)-URL zonder inloggegevens, querystring of fragment. Gebruik de widget-API-URL uit het installatiefragment, niet de dashboard-URL of een Convex-.cloud-client-URL. Afsluitende slashes en daarna een afsluitend /chat worden verwijderd. De client toont alleen-lezen apiKey en de genormaliseerde baseUrl.

De constructor geeft een gewone Error bij ontbrekende of ongeldige opties, ontbrekende, lege of niet-string sleutel of URL, een fetch die geen functie is, of een ongeldige baseUrl. Het pakket exporteert Chattybox, ChattyboxError en de types ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions en HostedWidgetHandle. Het bevat geen React-component of hooks. De ./browser IIFE-bundel biedt beide constructors op window.ChattyboxSDK, maar mount niet zelf een UI.

De gehoste widget vanuit code mounten​

Gebruik dit wanneer je de onderhouden zwevende interface van ChattyBox vanuit applicatiecode wilt initialiseren:

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget({ locale: 'fr', debug: false });

mountWidget() geeft een handle terug voordat script of UI gereed is. In de gepubliceerde SDK 0.1.4 delen identieke mounts het script en bezit elke handle een referentie: remove() is idempotent en alleen de laatste handle annuleert initialisatie, retries en een lopende chat, en verwijdert daarna UI, stijlen, fontlinks, script en de globale API. Een afwijkende sleutel, API-URL, scriptUrl, locale of debugoptie wordt geweigerd zolang er handles bestaan. Met widget.js v15 doet window.ChattyBox.destroy() dezelfde teardown. De gepubliceerde SDK 0.1.4 biedt geen ready-promise, containertarget of API voor reactieve locale-updates; de loader uit de huidige broncode volgt wél directe wijzigingen aan data-locale, zoals beschreven in de sectie Meertalige ondersteuning van de widgetgids. Gebruik één loader.

De SDK herkent handmatig toegevoegde loaders zonder markering niet. Combineer SDK-mounting daarom niet met een plug-in, GTM-tag of afzonderlijk script. Een eigen fetch uit de constructor wordt alleen door headlessmethoden gebruikt, niet door de gehoste widget. Opruimen kan een verzoek dat de server al heeft verwerkt niet ongedaan maken.

mountWidget(options?) geeft de handle synchroon terug. scriptUrl is standaard https://chattybox.ai/widget.js; wijzig die alleen voor een vertrouwde preview of self-hosted loader. Een niet-lege locale zet data-locale, mits het project allowLocaleOverride toestaat; een truthy debug zet data-debug="true". handle.element is het geïnjecteerde of hergebruikte HTMLScriptElement.

De gehoste loader v16 uit de huidige broncode probeert netwerkfouten, onderbroken succesvolle response-bodies, HTTP 429, HTTP 5xx en 409-responses met een leesbare Retry-After-header opnieuw met dezelfde body en idempotentiesleutel: maximaal 10 pogingen, zonder een automatische retry te plannen buiten het budget van 30 seconden. Dit is geen harde timeout voor een lopend verzoek. Leesbare Retry-After-wachttijden tellen mee. Na uitputting gebruikt Bericht opnieuw verzenden hetzelfde logische verzoek; een nieuwe vraag start een nieuw verzoek. Ongeldige JSON of een ongeldige responsevorm bij een succesvolle response is een terminale protocolfout. Cross-origin API-responses moeten Retry-After via Access-Control-Expose-Headers beschikbaar maken. Controleer de geleverde loader voordat je op dit gedrag vertrouwt.

Bouw je eigen UI​

Gebruik de onderstaande headlessmethoden wanneer je applicatie zelf de berichtenlijst, invoer, laad- en foutstatussen, citaten en toegankelijkheid beheert.

Een bericht verzenden​

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const answer = await chattybox.sendMessage({
message: 'How do I get started?',
});

console.log(answer.message);
console.log(answer.sources);

Stel PUBLIC_CHATTYBOX_API_URL in op de exacte widget-API-URL uit het fragment bij Installatie op website. De SDK accepteert zowel de deploymentroot als een URL die eindigt op /chat.

Het antwoord bevat:

VeldTypeBeschrijving
messagestringAntwoordtekst of het ingestelde fallbackbericht. Geef dit veilig weer als tekst of gesaniteerde Markdown, niet als onbewerkte HTML.
conversationIdstringIdentificatie om dit gesprek voort te zetten.
sourcesstring[]Bron-URL’s voor het antwoord; kan leeg zijn bij een fallback. Controleer vóór het weergeven van links of de URL’s HTTP(S) gebruiken.
providerErrorstring (optioneel, huidige bron)Een gestructureerde code voor een providerfout. Ontbreekt bij gewone antwoorden en ingestelde fallbacks; behandel onbekende codes als een algemene fout.
productFallback'no_context_ui' | 'no_context_question' (optioneel, huidige bron)Geeft aan dat het om producteigen tekst zonder context gaat en hoe de taal is gekozen; zie hieronder.

sendMessage(input) retourneert Promise<ChatResponse>. SendMessageInput accepteert message: string, optioneel conversationId: string | null en optioneel idempotencyKey: string. De SDK in de huidige broncode accepteert ook optioneel uiLocale: string; deze optie is niet beschikbaar in de gepubliceerde npm-SDK 0.1.4. De SDK uit de huidige broncode stuurt een opgegeven waarde ongewijzigd door en laat het veld weg als het ontbreekt of undefined is; deze SDK detecteert geen locale automatisch. De backend uit de huidige broncode valideert de waarde en normaliseert die naar een ondersteunde basistaal. Een ongeldige of niet-ondersteunde waarde geeft HTTP 400 Invalid uiLocale in plaats van stilzwijgend terug te vallen. uiLocale is door de aanroeper verstrekte presentatiecontext, geen authenticatie- of autorisatiecontrole.

Controleer vóór verzending dat het bericht niet leeg is en na het verwijderen van witruimte aan de uiteinden maximaal 2.000 tekens bevat. De backend handhaaft deze limiet, maar interne validatiefouten verschijnen momenteel als algemene HTTP 500-fouten.

De SDK verzendt de openbare API-sleutel in de JSON-body, maar geen paginacontext (sourceUrl of sourcePath) of modelopties. Headless sendMessage() biedt geen streaming, automatische retries, time-outs, AbortSignal-optie, opslag of UI-state. Een aangepaste fetch-implementatie kan het transportbeleid bepalen. SDK 0.1.4 probeert alleen getWidgetConfig() eenmaal opnieuw na HTTP 400; retries van de gehoste loader staan daar los van.

Gebruik bijvoorbeeld met de SDK en backend uit de huidige broncode chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }).

Voor producteigen fallbackberichten heeft een herkend taalsignaal in de vraag voorrang op uiLocale. Als 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 in plaats van de producteigen fallback zonder context. uiLocale vertaalt geen projecttekst in fallbacks en verandert geen door AI gegenereerde antwoorden; het garandeert evenmin de kwaliteit of taal van het antwoord.

De widget-/chat-API uit de huidige broncode voegt productFallback alleen toe aan producteigen antwoorden zonder context; de beschikbaarheid hangt af van de backendversie, niet van de SDK-versie. no_context_ui betekent dat de fallbacktaal is gekozen op basis van de UI- of standaardlocale, of niet kon worden bepaald; een aangepaste UI kan de tekst opnieuw lokaliseren met de actuele catalogusvermelding message.noContext. no_context_question betekent dat de bestaande classifier de taal van de vraag heeft herkend; behoud de geretourneerde tekst in message. De classifier kan de taal verkeerd herkennen. De marker ontbreekt bij aangepaste fallbacks, gewone antwoorden, providerfouten en legacyresponses. Leid de herkomst nooit af uit de tekst van message of uit het ontbreken van de marker, en negeer onbekende productFallback-waarden.

De gepubliceerde npm-SDK 0.1.4 declareert productFallback niet in ChatResponse, maar geeft het veld wel door in het geretourneerde JSON-object als de backend het aanlevert. Controleer veilig of de waarde een van de bekende waarden is voordat je die gebruikt. Er is geen algemeen veld wasAnswered of fallbackstatus; verzin dus geen gestructureerd resultaat voor een niet-ondersteund antwoord.

Herhaal bij een retry met dezelfde idempotentiesleutel exact dezelfde oorspronkelijke invoer, inclusief uiLocale (ook als die was weggelaten). De huidige backend neemt de genormaliseerde locale op in de fingerprint van het verzoek. Een identiek, voltooid verzoek kan opnieuw worden afgespeeld met het oorspronkelijk opgeslagen bericht en de marker, indien aanwezig, zonder het verzoek opnieuw uit te voeren.

Een gesprek voortzetten​

Bewaar de geretourneerde gespreks-ID in de UI-state en stuur die mee met het volgende bericht:

const followUp = await chattybox.sendMessage({
message: 'Can you explain the second step?',
conversationId: answer.conversationId,
});

Gebruik één gespreks-ID niet opnieuw voor niet-gerelateerde bezoekers. Maak een nieuw gesprek door conversationId bij hun eerste bericht weg te laten; null begint eveneens een nieuw gesprek. De ID groepeert opgeslagen berichten; bij dezelfde conversationId ontvangt het model maximaal 12 recente opgeslagen berichten, elk afgekapt op 2.000 tekens. Dit is beperkte context, geen volledig transcript of blijvend geheugen; herhaal oudere details wanneer nodig.

Veilig opnieuw proberen​

const input = {
message: 'Where is the API reference?',
idempotencyKey: crypto.randomUUID(),
};
const result = await chattybox.sendMessage(input);
// If the response is lost, retry the same input, including its original conversationId.

Gebruik voor elk logisch bericht een unieke idempotencyKey en bewaar de exacte invoer voor een retry. De SDK stuurt de sleutel als Idempotency-Key, maar maakt die niet zelf aan en probeert niet automatisch opnieuw. Sleutels gelden per project, bevatten 1–128 tekens en moeten overeenkomen met [A-Za-z0-9][A-Za-z0-9._:-]*. Een gewijzigde invoer, een nog lopend verzoek of een definitieve fout kan HTTP 409 geven. Probeer niet elke 409 blind opnieuw en maak na een onduidelijke transportfout geen nieuwe sleutel aan.

Replay is niet permanent: voltooide en mislukte records verlopen 24 uur na reservering, terwijl lopende records niet uitsluitend op basis van tijd worden vrijgegeven. Na het verlopen van een definitief record kan een retry opnieuw worden uitgevoerd. Beperk de retryperiode en onderzoek aanhoudende conflicten.

Fouten afhandelen​

import { Chattybox, ChattyboxError } from '@openstaticfish/chattybox';

try {
await chattybox.sendMessage({ message: 'Where is the API reference?' });
} catch (error) {
if (error instanceof ChattyboxError) {
console.error(error.status, error.code, error.message);
}
}

ChattyboxError.status bevat de HTTP-status; code bestaat alleen wanneer de API een string code levert, wat bij de meeste huidige widget-API-fouten niet gebeurt. Niet-2xx-responses, een niet-lege string error ook bij HTTP 200, ongeldige JSON en JSON die geen object is, geven ChattyboxError. Netwerk- en fetchfouten blijven onveranderd. SDK 0.1.4 verpakt ook onleesbare response-bodies als ChattyboxError met RESPONSE_BODY_READ_FAILED. Succesvolle JSON-objecten worden naar het gedeclareerde type gecast zonder runtimevalidatie van elk veld.

Veelvoorkomende HTTP-statussen zijn 400 bij ongeldige invoer of niet-ondersteunde vertaal-locales, 401 bij sleutel- of originfouten, 403 bij een uitgeschakelde projectwidget (ook bij headless chat), 409 bij idempotentieconflicten, 413 bij chat-body’s groter dan 65.536 bytes, 429 bij snelheidsbeperking en 500 bij interne fouten. De SDK geeft responseheaders niet terug op het resultaat of de fout. Fallbacks kunnen lege sources hebben en er is geen aparte openbare antwoordstatus. Gebruik per logisch bericht een unieke idempotentiesleutel en herhaal zo nodig exact dezelfde invoer, niet blind elke 409.

Projectinstellingen en vertalingen hergebruiken​

De SDK biedt ook getWidgetConfig() en getWidgetTranslations(locale). Deze methoden ondersteunen clients die de projectinstellingen en gelokaliseerde labels van de gehoste widget willen reproduceren:

const [config, labels] = await Promise.all([
chattybox.getWidgetConfig(),
chattybox.getWidgetTranslations('en'),
]);

In de huidige SDK-broncode heeft WidgetConfig de optionele velden headerTitleIsDefault?: boolean en welcomeMessageIsDefault?: boolean. Elke flag beschrijft de bijbehorende tekst: true betekent een gelokaliseerde productstandaard, terwijl false betekent dat het een aangepaste tekenreeks is die behouden moet blijven. Als een flag ontbreekt, ook in oudere responses, is de herkomst onbekend; vergelijk de tekst nooit met een standaardwaarde om de herkomst af te leiden. De beschikbaarheid hangt af van de backend, niet van de SDK-versie. De gepubliceerde SDK 0.1.4 declareert deze flags niet als booleans, maar het type Record<string, unknown> en de ongewijzigde JSON-response maken het mogelijk de waarden veilig te verfijnen wanneer ze zijn meegeleverd. Succesvolle responses worden niet veld voor veld gevalideerd of naar andere typen omgezet.

Een volledig aangepaste UI kan ze negeren. Bewaar de conversationId van elke bezoeker in diens browser- of sessiestatus; deel nooit één globale gespreks-ID.

getWidgetConfig() geeft Promise<WidgetConfig> terug en gebruikt Authorization: Bearer. SDK 0.1.4 probeert alleen na HTTP 400 precies één keer opnieuw met een gecodeerde sleutel in de querystring. WidgetConfig is Record<string, unknown> met optionele getypeerde velden voor inschakeling, kleuren, positie, titel en welkomstbericht, branding, pictogrammen en locale-instellingen. Controleer aanvullende onbekende velden voordat je ze gebruikt. Zie De gehoste widget aanpassen voor huidige servervelden en standaardwaarden. Een geslaagd configuratieverzoek markeert het project ook als widget-geïnstalleerd, zelfs als je aangepaste client geen widget toont.

getWidgetTranslations(locale) geeft Promise<WidgetTranslations> terug met translations: Record<string, string>, dir: 'ltr' | 'rtl' en de door de server gekozen locale: string. Dit endpoint is openbaar en gebruikt de API-sleutel of projecttaalinstellingen niet. Gebruik en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy of cs; een lege string selecteert Engels op de server. De SDK URL-encodeert de locale maar normaliseert die niet: fr-CA en FR geven HTTP 400. Alle huidige catalogi zijn links-naar-rechts en kunnen één uur worden gecachet.

Bepaal voor een aangepaste UI zelf de gewenste locale, respecteer bij het nabouwen van gehost gedrag allowLocaleOverride en fixed/auto, en bied fallbacks voor ontbrekende vertaalsleutels. Een headless client op basis van de huidige broncode kan daarnaast uiLocale opgeven voor producteigen fallbackberichten, zoals hierboven beschreven. De locale vertaalt de vraag of geïndexeerde inhoud niet en garandeert geen antwoordkwaliteit of taal van door AI gegenereerde antwoorden.

Volgende stappen​