JavaScript-SDK

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();

// Call this from your component's cleanup lifecycle when appropriate.
// widget.remove();

Roep mountWidget() aan in browsercode vanuit de component of layout waar de onderhouden interface beschikbaar moet zijn. Je kunt { locale: 'fr' } doorgeven voor een locale die specifiek is voor een route.

Je openbare configuratie ophalen

1. Maak een project en indexeer je content.
2. Test representatieve vragen in het dashboard.
3. Open Public Keys, maak een browsersleutel aan en beperk de toegestane origins.
4. Open Embed, selecteer die sleutel en kopieer de widget-API-URL die bij het gegenereerde fragment wordt getoond.

Openbare widget-API-sleutels zijn bedoeld om in browsercode te staan. Ze identificeren een project, maar zijn geen beheergegevens. Beperk browsersleutels tot de domeinen die je chatbot mogen aanroepen. Het pakket is een ESM-client voor actuele Node.js- en browserapplicaties die fetch aanbieden.

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();

// Optional cleanup for a component lifecycle:
widget.remove();

De onderhouden UI wordt één keer geladen en is niet beschikbaar tijdens server-side rendering.

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.

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.

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 is aanwezig wanneer de API een gestructureerde foutcode terugstuurt.

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.

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.