JavaScript-SDK

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

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

Rufen Sie mountWidget() im Browsercode aus der Komponente oder dem Layout auf, in dem die gepflegte Oberfläche verfügbar sein soll. Sie können { locale: 'fr' } für eine sprachspezifische Route übergeben.

Ö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, erstellen Sie einen Browserschlüssel und beschränken Sie seine zulässigen 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 Widget-API-Schlüssel sind dafür vorgesehen, in Browsercode zu erscheinen. Sie identifizieren ein Projekt, sind aber keine Verwaltungszugangsdaten. Beschränken Sie Browserschlüssel auf die Domains, die den Aufruf Ihres Chatbots erlauben sollen. Das Paket ist ein ESM-Client für aktuelle Node.js- und Browseranwendungen, die fetch bereitstellen.

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

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

Die gepflegte Benutzeroberfläche wird einmal geladen und ist beim serverseitigen Rendern nicht verfügbar.

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.

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.

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 ist vorhanden, wenn die API einen strukturierten Fehlercode zurückgibt.

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.

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.