JavaScript-SDK

:::note Versionsstatus Das veröffentlichte npm-SDK 0.1.4 validiert baseUrl, kapselt nicht lesbare Response-Bodies und wiederholt Config-HTTP-400 genau einmal. Mit widget.js v15 steht remove()/window.ChattyBox.destroy() für Teardown bereit; Headless-sendMessage() wiederholt nicht automatisch. :::

Das npm-Paket ist die empfohlene Integrationsmethode für ChattyBox. Importieren Sie einen Client in Ihre Anwendung, konfigurieren Sie den öffentlichen Schlüssel und die API-URL und binden Sie dann die gepflegte Benutzeroberfläche dort ein, wo sie Ihre Anwendung benötigt, oder verwenden Sie die Headless-Methoden mit Ihren eigenen Komponenten.

Schnelleinstieg

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

// Den Loader für die gesamte Seitenlebensdauer behalten.

Rufen Sie mountWidget() nach document.body im Browser aus einer persistenten Hülle auf. Es fügt ein schwebendes Widget unter document.body ein, nicht in die Komponente. { locale: 'fr' } fordert die Sprache nur bei Initialisierung an und nur, wenn das Projekt Script-Overrides erlaubt.

Öffentliche Konfiguration abrufen

1. Erstellen Sie ein Projekt und indexieren Sie Ihre Inhalte.
2. Testen Sie repräsentative Fragen im Dashboard.
3. Öffnen Sie Public Keys und erstellen Sie einen Browserschlüssel. Er funktioniert standardmäßig für Produktion, Vorschau, Staging und localhost; aktivieren Sie Edit origins nur optional für genaue Origins.
4. Öffnen Sie Embed, wählen Sie diesen Schlüssel aus und kopieren Sie die Widget-API-URL, die zusammen mit dem generierten Snippet angezeigt wird.

Öffentliche Schlüssel sind für Browsercode bestimmt und keine Verwaltungszugangsdaten. Eine optionale Beschränkung vergleicht genau Schema, Host und Port mit Origin oder der Origin von Referer; sie ist keine Authentifizierung. Das ESM-Paket läuft in Node.js und Browsern mit fetch.

Gehostetes Widget aus Code einbinden

Verwenden Sie dies, wenn Sie die gepflegte ChattyBox-Oberfläche nutzen und gleichzeitig aus Anwendungscode steuern möchten, wo sie eingebunden wird:

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() gibt ein Handle zurück, bevor Script oder UI bereit sind. Im veröffentlichten SDK 0.1.4 teilen identische Mounts das Script und jedes Handle hält eine Referenz: remove() ist idempotent und erst das letzte Handle bricht Initialisierung, Wiederholungen und laufenden Chat ab und entfernt dann UI, Styles, Font-Links, Script und globale API. Abweichender Schlüssel, API-URL, scriptUrl, Locale oder Debug-Option wird abgelehnt, solange Handles bestehen. Mit widget.js v15 führt window.ChattyBox.destroy() denselben Teardown aus. Es gibt kein Ready-Promise, Container-Ziel oder reaktives Locale-Update; kombinieren Sie nicht SDK, Plugin, GTM und manuellem Script auf einer Seite.

Eigene Benutzeroberfläche erstellen

Verwenden Sie die folgenden Headless-Methoden, wenn Ihre Anwendung Nachrichtenliste, Eingabe, Lade- und Fehlerzustände, Quellenangaben und Barrierefreiheit selbst verwaltet.

Nachricht senden

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

Setzen Sie PUBLIC_CHATTYBOX_API_URL auf die exakte Widget-API-URL aus dem Tab Embed. Das SDK akzeptiert sowohl die Deployment-Root als auch eine URL mit dem Ende /chat.

Die Antwort enthält:

Feld	Typ	Beschreibung
message	string	Die generierte Antwort.
conversationId	string	Kennung zum Fortsetzen dieser Unterhaltung.
sources	string[]	Für die Antwort abgerufene Quell-URLs.

sendMessage() akzeptiert nur message, optionale conversationId und optionalen idempotencyKey. Es sendet weder sourceUrl, sourcePath, Locale noch Modelloptionen. Prüfen Sie nichtleere Nachrichten bis 2.000 Zeichen; SDK bietet weder Streaming, Timeout, AbortSignal noch automatische Retries.

Unterhaltung fortsetzen

Speichern Sie die zurückgegebene Konversations-ID im Zustand Ihrer Benutzeroberfläche und senden Sie sie mit der nächsten Nachricht:

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

Verwenden Sie nicht dieselbe Konversations-ID für voneinander unabhängige Besucher. Erstellen Sie für die erste Nachricht eine neue Unterhaltung, indem Sie conversationId weglassen. Die ID gruppiert gespeicherte Nachrichten, frühere Turns erreichen das Modell aber derzeit nicht; Follow-ups müssen eigenständig sein.

Fehler behandeln

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 enthält den HTTP-Status; code existiert nur, falls ihn die API liefert. Netzwerkfehler werden nicht umschlossen. Fallbacks können leere sources haben und es gibt keinen separaten öffentlichen Antwortstatus. Nutzen Sie pro logischer Nachricht einen eindeutigen Idempotenzschlüssel und wiederholen Sie bei Bedarf exakt dieselbe Eingabe, nicht blind jeden 409.

Projekteinstellungen und Übersetzungen wiederverwenden

Das SDK stellt außerdem getWidgetConfig() und getWidgetTranslations(locale) bereit. Diese Methoden unterstützen Clients, die die Projekteinstellungen und lokalisierten Bezeichnungen des gehosteten Widgets nachbilden möchten:

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

Eine vollständig eigene Benutzeroberfläche kann diese Methoden ignorieren. Bewahren Sie die conversationId jedes Besuchers im Browser- oder Sitzungszustand dieses Besuchers auf und teilen Sie niemals eine globale Konversations-ID.

Wenn Sie das gehostete Verhalten nachbilden, beachten Sie allowLocaleOverride sowie fixed/auto. Die Locale übersetzt weder Anfrage noch indexierte Inhalte und garantiert keine Antwortqualität. getWidgetTranslations() normalisiert fr-CA oder FR nicht wie der gehostete Loader.

Nächste Schritte

• Bevorzugen Sie eine gepflegte Benutzeroberfläche ohne Build-Schritt? Installieren Sie widget.js.
• Passen Sie die gehostete Benutzeroberfläche unter Anpassung des gehosteten Widgets an.
• Testen Sie vor dem Start Origin-Beschränkungen, Fallback-Antworten, Quellenangaben und das mobile Verhalten mit der Start-Checkliste.