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 te integreren. Importeer één client in je applicatie, configureer de openbare sleutel en API-URL en mount daarna de onderhouden interface waar je applicatie die nodig heeft, of gebruik de headlessmethoden met je eigen componenten.

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() na document.body aan in de browser vanuit een persistente shell. Het voegt een zwevende widget toe onder document.body, niet in je component. { locale: 'fr' } vraagt die taal alleen bij initialisatie aan en alleen als het project script-overschrijvingen toestaat.

Je openbare configuratie ophalen

1. Maak een project en indexeer je content.
2. Test representatieve vragen in het dashboard.
3. Open Public Keys en maak een browsersleutel. Die werkt standaard voor productie, preview, staging en localhost; gebruik Edit origins alleen optioneel voor exacte origins.
4. Open Embed, selecteer die sleutel en kopieer de widget-API-URL die bij het gegenereerde fragment wordt getoond.

Openbare sleutels zijn bedoeld voor browsercode, niet als beheerdersreferenties. Een optionele beperking vergelijkt schema, host en poort exact met Origin of de origin van Referer; het is geen authenticatie. Het ESM-pakket werkt in Node.js en browsers met fetch.

De gehoste widget vanuit code mounten

Gebruik dit wanneer je de onderhouden interface van ChattyBox wilt en vanuit applicatiecode wilt bepalen waar die wordt gemount:

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. Er is geen ready-promise, containertarget of reactieve locale-update.

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 tabblad Embed. De SDK accepteert zowel de deploymentroot als een URL die eindigt op /chat.

Het antwoord bevat:

Veld	Type	Beschrijving
message	string	Het gegenereerde antwoord.
conversationId	string	Identificatie om dit gesprek voort te zetten.
sources	string[]	Bron-URL’s die voor het antwoord zijn opgehaald.

sendMessage() accepteert alleen message, optionele conversationId en optionele idempotencyKey. Het verzendt geen sourceUrl, sourcePath, locale of modelopties. Valideer niet-lege berichten tot 2.000 tekens; SDK biedt geen streaming, timeout, AbortSignal of automatische retries.

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. De ID groepeert opgeslagen berichten, maar eerdere beurten bereiken het model momenteel niet; vervolgvragen moeten zelfstandig zijn.

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 die levert. Netwerkfouten worden niet verpakt. 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'),
]);

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

Respecteer bij het nabouwen van gehost gedrag allowLocaleOverride en fixed/auto. Locale vertaalt de vraag of geïndexeerde inhoud niet en garandeert geen antwoordkwaliteit. getWidgetTranslations() normaliseert fr-CA of FR niet zoals de gehoste loader.

Volgende stappen

• Liever een onderhouden UI zonder build? Installeer widget.js.
• Pas de gehoste UI aan via De gehoste widget aanpassen.
• Test vóór de lancering originbeperkingen, fallbackantwoorden, citaten en mobiel gedrag met de launchchecklist.