Zum Hauptinhalt springen

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() im Browser aus einem dauerhaft eingebundenen Layout auf, sobald document.body vorhanden ist. Das Widget wird schwebend unter document.body eingefügt, nicht in Ihre Komponente. Die Option { locale: 'fr' } setzt data-locale beim Mounten, sofern das Projekt Script-Overrides erlaubt; das SDK bietet keine reaktive API zum Ändern dieser Option. Der Loader im aktuellen Quellcode kann jedoch auf spätere Änderungen an data-locale oder <html lang> reagieren, wie im Abschnitt zur Mehrsprachigkeit des Widgets beschrieben. Prüfen Sie den bereitgestellten Loader, bevor Sie sich darauf verlassen.

Die Namen import.meta.env.PUBLIC_* sind Beispiele. Verwenden Sie die öffentliche Konvention Ihres Frameworks, etwa import.meta.env.VITE_* für Vite oder process.env.NEXT_PUBLIC_* für Next.js. In Node.js lesen und validieren Sie stattdessen process.env-Werte.

Öffentliche Konfiguration abrufen​

  1. Erstellen Sie ein Projekt und indexieren Sie Ihre Inhalte.
  2. Testen Sie repräsentative Fragen unter Chatbot testen.
  3. Prüfen oder erstellen Sie unter Installieren → Schlüssel und Domains einen öffentlichen Schlüssel und prüfen Sie seine Origins. Uneingeschränkte Schlüssel funktionieren über Origins hinweg; ein für eine Website vorbereiteter Schlüssel kann bereits eingeschränkt sein. Mit Origins bearbeiten verwalten Sie optionale Einschränkungen.
  4. Geben Sie unter Installieren → Installation auf der Website eine HTTP(S)-Website-URL ein, wählen Sie einen passenden Schlüssel und kopieren Sie die Widget-API-URL aus dem generierten Snippet. Die Auswahl zeigt nur nicht abgelaufene Schlüssel, die uneingeschränkt oder für die Origin dieser URL zugelassen sind. Geben Sie für einen eingeschränkten Schlüssel eine erlaubte Origin ein; unter Schlüssel und zulässige Domains verwalten können Sie seine Einschränkungen prüfen. Falls das Formular nicht verfügbar ist, schließen Sie zuerst den im Dashboard angezeigten Einrichtungsschritt ab.

Ö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, nicht Pfade oder Wildcard-Subdomains; sie ist keine Authentifizierung. Das ESM-Paket läuft in Node.js und Browsern mit fetch.

SDK 0.1.4 verlangt eine absolute HTTP(S)-baseUrl ohne Zugangsdaten, Query-String oder Fragment. Kopieren Sie die Widget-API-URL, nicht die Dashboard-URL oder eine Convex-.cloud-URL. Bei eingeschränkten Schlüsseln führen fehlende oder nicht erlaubte Origins zu HTTP 401 Invalid API key; Node.js-fetch sendet Origin oder Referer nicht automatisch. Origin-Prüfungen sind keine Authentifizierung und können gefälschte Header von Nicht-Browser-Clients nicht verhindern.

Konstruktor und Exporte​

new Chattybox(options) erwartet einen nicht leeren öffentlichen apiKey und eine nicht leere baseUrl. Optional kann fetch als kompatible Funktion übergeben werden; andernfalls wird das globale fetch verwendet. Abschließende Schrägstriche und danach ein abschließendes /chat werden aus der Basis-URL entfernt. apiKey und die normalisierte baseUrl sind als schreibgeschützte Eigenschaften verfügbar. Fehlende oder ungültige Optionen, ein ungültiges fetch oder eine ungültige URL führen zu einem gewöhnlichen Error.

Das Paket exportiert Chattybox, ChattyboxError sowie die Typen ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions und HostedWidgetHandle. Es enthält keine React-Komponente oder Hooks. Das ./browser-IIFE-Bundle stellt die beiden Konstruktoren unter window.ChattyboxSDK bereit; allein durch das Laden wird keine Oberfläche eingebunden.

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: Rufen Sie remove() für jedes Handle auf. Das letzte Handle signalisiert den Abbau und entfernt das Script; mit dem gehosteten widget.js v15 bricht dieses Signal auch Initialisierung, Wiederholungen und laufenden Chat ab und entfernt die UI und ihre Ressourcen. Bereits serverseitig verarbeitete Anfragen lassen sich nicht rückgängig machen. Abweichender Schlüssel, API-URL, scriptUrl, Locale oder Debug-Option wird abgelehnt, solange Handles bestehen. Mit widget.js v15 baut window.ChattyBox.destroy() das Widget ebenfalls ab. Das SDK bietet weder ein Ready-Promise noch ein Container-Ziel oder eine reaktive Locale-Update-API; kombinieren Sie nicht SDK, Plugin, GTM und manuelles Script auf einer Seite.

scriptUrl verwendet standardmäßig https://chattybox.ai/widget.js; überschreiben Sie die URL nur für einen vertrauenswürdigen Vorschau- oder selbst gehosteten Loader. locale setzt bei nicht leerem Wert data-locale, sofern das Projekt Overrides erlaubt; debug setzt nur bei einem wahrheitswertigen Wert data-debug="true". handle.element ist das eingefügte oder wiederverwendete Script-Element. Nicht markierte manuelle Loader erkennt das SDK nicht. Ein im Konstruktor übergebenes fetch wird nur für Headless-Methoden verwendet, nicht für das gehostete Widget. Prüfen Sie vor dem Einsatz die Version des bereitgestellten Loaders.

Der gehostete Loader v16 im aktuellen Quellcode wiederholt bestimmte Transportfehler, unterbrochene erfolgreiche Antwort-Bodies, HTTP 409 mit lesbarem Retry-After sowie Rate-Limits und Serverfehler mit demselben Request-Body und Idempotenzschlüssel. Er unternimmt höchstens 10 Versuche und plant keinen automatischen Retry über 30 Sekunden hinaus; lesbare Retry-After-Verzögerungen zählen zu diesem Zeitraum. Nach Ausschöpfung verwendet Nachricht erneut senden dieselbe logische Anfrage; eine neue Frage startet eine neue Anfrage. Ungültiges JSON oder ein ungültiges Antwortformat bei erfolgreichem Status ist ein abschließender Protokollfehler. Bei Cross-Origin-Antworten muss Retry-After über Access-Control-Expose-Headers freigegeben werden. Prüfen Sie den bereitgestellten Loader, bevor Sie sich auf dieses Verhalten verlassen.

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 Installieren → Installation auf der Website. Das SDK akzeptiert sowohl die Deployment-Root als auch eine URL mit dem Ende /chat.

Die Antwort enthält:

FeldTypBeschreibung
messagestringAntwort oder konfigurierte Fallback-Nachricht; sicher als Text oder bereinigtes Markdown, nicht als rohes HTML darstellen.
conversationIdstringKennung zum Fortsetzen dieser Unterhaltung.
sourcesstring[]Quell-URLs; bei einem Fallback gegebenenfalls leer. HTTP(S)-URLs vor dem Verlinken validieren.
providerErrorstring (optional, aktueller Quellcode)Strukturierter Fehlercode für einen Provider-Ausfall. Fehlt bei normalen Antworten und konfigurierten Fallbacks; unbekannte Codes als allgemeinen Fehler behandeln.
productFallback'no_context_ui' | 'no_context_question' (optional, aktuelles Backend)Kennzeichnet eine produktseitige Fallback-Nachricht ohne Kontext und wie deren Sprache ausgewählt wurde; siehe unten.

sendMessage(input) gibt Promise<ChatResponse> zurück. SendMessageInput akzeptiert message: string, optional conversationId: string | null und optional idempotencyKey: string. Der aktuelle Quellcode akzeptiert außerdem optional uiLocale: string; diese Option gibt es im veröffentlichten SDK 0.1.4 nicht. Das SDK sendet den öffentlichen API-Schlüssel im JSON-Body. Es sendet weder Seitenkontext (sourceUrl oder sourcePath) noch Modelloptionen. Validieren Sie vor dem Senden, dass die Nachricht nicht leer ist und nach dem Trimmen höchstens 2.000 Zeichen umfasst; das Backend erzwingt dieses Limit, interne Validierungsfehler werden derzeit jedoch als generische HTTP-500-Fehler ausgegeben.

Verwenden Sie beispielsweise mit dem SDK und Backend aus dem aktuellen Quellcode chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). Das SDK leitet eine angegebene Locale unverändert weiter und lässt sie weg, wenn sie fehlt oder undefined ist; es ermittelt keine Locale automatisch. Der Server validiert sie und normalisiert sie auf eine unterstützte Basissprache. Fehlerhafte oder nicht unterstützte Werte führen zu HTTP 400 Invalid uiLocale, statt stillschweigend auf eine andere Sprache zurückzufallen. Die Locale ist vom Aufrufer bereitgestellter Präsentationskontext, keine Authentifizierungs- oder Autorisierungskontrolle.

Ein erkanntes Signal für die Fragesprache hat bei produktseitigen Fallback-Nachrichten Vorrang vor uiLocale. Wenn die Erkennung nicht eindeutig ist oder sich allein auf die ASCII-Englisch-Heuristik stützt, kann die UI-Locale deren Sprache bestimmen; ohne eines dieser Signale gelten die Produkt-Defaults. Eine vom Projekt verfasste Fallback-Nachricht wird unverändert statt des produktseitigen Fallbacks ohne Kontext verwendet. Die UI-Locale übersetzt weder den vom Projekt verfassten Fallback-Text noch KI-generierte Ausgaben und garantiert weder Antwortqualität noch Antwortsprache.

Die aktuelle Widget-/Chat-API des Backends fügt productFallback nur produktseitigen Fallback-Antworten ohne Kontext hinzu; ob das Feld verfügbar ist, hängt von der Backend-Version ab, nicht von der SDK-Version. no_context_ui bedeutet, dass die Fallback-Sprache anhand der UI- oder Standardsprache ausgewählt wurde oder unbestimmt war; eine eigene Benutzeroberfläche kann den Text mithilfe des aktuellen Katalogeintrags message.noContext lokalisieren. no_context_question bedeutet, dass der vorhandene Klassifikator die Fragesprache erkannt hat; übernehmen Sie den zurückgegebenen Nachrichtentext unverändert. Der Klassifikator kann sich irren: Der Marker garantiert nicht, dass die Sprache korrekt erkannt wurde. Bei eigenen Fallback-Nachrichten, normalen Antworten, Provider-Ausfällen und Antworten älterer Backend-Versionen fehlt der Marker. Leiten Sie die Herkunft niemals aus dem Nachrichtentext (auch nicht aus einer exakten Übereinstimmung mit einem bekannten Text) oder aus einem fehlenden Marker ab; unbekannte Markerwerte sind zu ignorieren.

Das veröffentlichte SDK 0.1.4 deklariert productFallback nicht in ChatResponse, leitet das Feld aber im zurückgegebenen JSON-Objekt weiter, wenn das Backend es bereitstellt. Grenzen Sie den Wert vor der Verwendung sicher ein. Es gibt kein allgemeines Feld wasAnswered und kein Fallback-Statusfeld; erfinden Sie kein strukturiertes Ergebnis für eine nicht unterstützte Antwort.

sendMessage() bietet weder Streaming, automatische Wiederholungen, Timeouts, eine AbortSignal-Option, Speicherung noch UI-Zustand. Eine eigene fetch-Implementierung kann die Transportstrategie übernehmen. Die Aussage zu fehlenden Wiederholungen gilt für Headless-Chat: SDK 0.1.4 wiederholt nur getWidgetConfig() einmal nach HTTP 400; der gehostete Loader v15 wiederholt separat seine Start-GETs.

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; bei derselben conversationId erhält das Modell bis zu 12 aktuelle gespeicherte Nachrichten mit jeweils höchstens 2.000 Zeichen. Das ist begrenzter Kontext, kein vollständiges Transkript oder dauerhaftes Gedächtnis; ergänzen Sie ältere Details bei Bedarf.

Auch null startet eine neue Unterhaltung. Abgeschlossene oder fehlgeschlagene Idempotenzdatensätze laufen 24 Stunden nach ihrer Reservierung ab; ein späterer Retry kann erneut ausgeführt werden. Ausstehende Datensätze werden nicht allein durch Zeitablauf freigegeben. Begrenzen Sie daher den Wiederholungszeitraum und untersuchen Sie anhaltende Konflikte.

Wiederholungssicherheit​

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.

Vergeben Sie pro logischer Nachricht einen eindeutigen idempotencyKey und bewahren Sie für einen Retry die vollständige ursprüngliche Eingabe einschließlich conversationId und uiLocale beziehungsweise dessen Fehlen auf. Das SDK sendet den Schlüssel als Idempotency-Key, erzeugt ihn aber nicht selbst und wiederholt die Nachricht nicht automatisch. Schlüssel gelten pro Projekt, sind 1 bis 128 Zeichen lang und müssen [A-Za-z0-9][A-Za-z0-9._:-]* entsprechen. Geänderte Eingaben, laufende oder abschließend fehlgeschlagene Anfragen können HTTP 409 auslösen. Wiederholen Sie nicht jeden 409 blind und erzeugen Sie nach einem unklaren Transportfehler keinen neuen Schlüssel.

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. Eine identische abgeschlossene Anfrage kann ohne erneute Ausführung wiederholt werden und liefert exakt die ursprüngliche Antwort einschließlich des ursprünglichen Markers, falls vorhanden. Bewahren Sie bei einem Retry das ursprüngliche uiLocale unverändert auf, auch wenn es in der ursprünglichen Eingabe fehlte; der aktuelle Server nimmt die normalisierte Locale in den Request-Fingerprint auf.

Nicht-2xx-Antworten, ein nicht leerer String error auch bei HTTP 200, ungültiges JSON und JSON, das kein Objekt ist, lösen ChattyboxError aus. SDK 0.1.4 kapselt auch nicht lesbare Antwort-Bodies mit RESPONSE_BODY_READ_FAILED. Erfolgreiche JSON-Objekte werden ohne feldweise Laufzeitvalidierung auf den deklarierten Typ übertragen. Häufige Statuscodes sind 400 für fehlerhafte Eingaben oder nicht unterstützte Übersetzungs-Locales, 401 für Schlüssel- oder Origin-Fehler, 403 für ein deaktiviertes Widget einschließlich Headless-Chat, 409 für Idempotenzkonflikte, 413 für Chat-Bodies über 65.536 Bytes, 429 für Rate-Limits und 500 für interne Fehler. Das SDK stellt Response-Header weder im Ergebnis noch im Fehler bereit.

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.

getWidgetConfig() gibt Promise<WidgetConfig> zurück und authentifiziert sich mit Authorization: Bearer. SDK 0.1.4 wiederholt den Abruf nur nach HTTP 400 genau einmal mit einem URL-kodierten Schlüssel im Query-String, etwa für zwischengeschaltete Systeme, die den Header entfernen. WidgetConfig ist ein Record<string, unknown> mit optional typisierten Einstellungen für Aktivierung, Farben, Position, Titel, Begrüßung, Branding, Symbole und Locale. Grenzen Sie unbekannte Felder vor der Verwendung ein. Ein erfolgreicher Konfigurationsabruf markiert das Projekt auch dann als Widget-installiert, wenn der eigene Client kein Widget anzeigt; aktuelle Serverfelder und Standardwerte stehen unter Anpassung des gehosteten Widgets.

Der aktuelle SDK-Quellcode definiert headerTitleIsDefault?: boolean und welcomeMessageIsDefault?: boolean als Felder von WidgetConfig. Jedes Flag beschreibt den zugehörigen Text: true bedeutet einen lokalisierten Produktstandard, während false einen benutzerdefinierten Text bezeichnet, der beibehalten werden sollte. Fehlt ein Flag – auch in älteren Antworten –, ist seine Herkunft unbekannt; leiten Sie sie niemals durch Vergleich des Textes mit einem Standardwert ab. Die Verfügbarkeit hängt von der Backend-Version ab, nicht von der SDK-Version. Das veröffentlichte SDK 0.1.4 deklariert diese Flags nicht als Booleans, aber sein Typ Record<string, unknown> und die unveränderte Weitergabe der JSON-Antwort ermöglichen es Aufrufern, sie bei Vorhandensein sicher auf ihren Typ einzugrenzen. Erfolgreiche Antworten werden weder feldweise validiert noch umgewandelt.

getWidgetTranslations(locale) gibt Promise<WidgetTranslations> mit translations: Record<string, string>, dir: 'ltr' | 'rtl' und der vom Server gewählten locale: string zurück. Der öffentliche Endpunkt verwendet weder den API-Schlüssel noch die Locale-Einstellungen des Projekts. Unterstützt werden en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy und cs. Das SDK URL-kodiert, normalisiert aber nicht: fr-CA und FR liefern HTTP 400. Eine leere Zeichenfolge wählt serverseitig Englisch. Alle aktuellen Kataloge sind links-nach-rechts und können eine Stunde zwischengespeichert werden.

Wenn Sie das gehostete Verhalten nachbilden, bestimmen Sie die gewünschte Locale selbst, beachten Sie allowLocaleOverride sowie fixed/auto und sehen Sie Fallbacks für fehlende Übersetzungsschlüssel vor. Diese Einstellungen steuern UI-Labels; Headless-Clients aus dem aktuellen Quellcode können uiLocale separat für produktseitige Fallback-Nachrichten übergeben. Die Locale übersetzt weder Anfrage noch indexierte Inhalte und garantiert weder Antwortqualität noch Sprache der KI-Antwort.

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 Fallback-Antworten, Quellenangaben und das mobile Verhalten mit der Start-Checkliste; testen Sie exakte Origins zusätzlich, wenn Sie eine Einschränkung aktivieren.