JavaScript SDK

:::note Stan wersji Opublikowane npm SDK 0.1.4 waliduje baseUrl, opakowuje nieczytelne treści odpowiedzi i tylko raz ponawia config HTTP 400. Z widget.js v15 remove()/window.ChattyBox.destroy() obsługują teardown; headless sendMessage() nie ponawia automatycznie. :::

Pakiet npm to zalecany sposób integracji z ChattyBox. Skonfiguruj jednego klienta i załaduj utrzymywany pływający widżet z trwałego układu przeglądarki albo użyj metod headless z własnymi komponentami.

Szybki start

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

// Zachowaj loader przez cały czas życia strony, także przy nawigacji SPA.

Wywołuj mountWidget() po utworzeniu document.body, nigdy podczas renderowania ani SSR. Widżet jest dodawany pod document.body, nie wewnątrz komponentu; { locale: 'fr' } działa tylko przy dozwolonym nadpisaniu skryptem i wyłącznie podczas inicjalizacji.

Uzyskaj konfigurację publiczną

1. Utwórz projekt i zindeksuj treści.
2. Przetestuj reprezentatywne pytania w panelu.
3. Otwórz Public Keys i utwórz klucz przeglądarkowy. Ograniczenie dokładnych originów jest opcjonalne.
4. Otwórz Embed, wybierz ten klucz i skopiuj adres URL API widżetu wyświetlany obok wygenerowanego fragmentu.

Publiczne klucze API widżetu są przeznaczone do umieszczania w kodzie przeglądarki. Identyfikują projekt, ale nie są danymi uwierzytelniającymi do zarządzania nim. Ogranicz klucze przeglądarkowe do domen, które powinny mieć możliwość wywoływania chatbota. Pakiet jest klientem ESM dla współczesnych aplikacji Node.js i przeglądarek udostępniających fetch.

Zamontuj hostowany widżet z poziomu kodu

Użyj tej opcji, gdy chcesz korzystać z utrzymywanego interfejsu ChattyBox, ale jednocześnie kontrolować miejsce jego montowania z poziomu kodu aplikacji:

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

// Używaj widget.remove() do zamierzonego teardownu.

mountWidget() zwraca handle przed gotowością skryptu lub UI. W opublikowanym SDK 0.1.4 identyczne montaże współdzielą skrypt, a każdy handle ma referencję: remove() jest idempotentne i dopiero ostatni handle anuluje inicjalizację, ponowienia oraz trwający chat, po czym usuwa UI, style, linki fontów, skrypt i globalne API. Inny klucz, URL API, scriptUrl, locale lub opcja debug jest odrzucana, dopóki istnieją handle. Z widget.js v15 to samo robi window.ChattyBox.destroy(). Nie łącz SDK z drugim loaderem, GTM ani wtyczką.

Zbuduj własny interfejs

Użyj poniższych metod headless, gdy aplikacja zarządza listą wiadomości, polem wprowadzania, stanami ładowania i błędów, cytowaniami oraz dostępnością.

Wyślij wiadomość

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

Ustaw PUBLIC_CHATTYBOX_API_URL na dokładny adres URL API widżetu z karty Embed. SDK akceptuje zarówno główny adres wdrożenia, jak i adres kończący się na /chat.

Odpowiedź zawiera:

Pole	Typ	Opis
message	string	Odpowiedź albo komunikat fallback; renderuj jako tekst lub bezpieczny Markdown.
conversationId	string	Identyfikator używany do kontynuowania tej konwersacji.
sources	string[]	Adresy źródeł; fallback może mieć pustą listę.

Kontynuuj konwersację

Zachowaj zwrócony identyfikator konwersacji w stanie interfejsu i wyślij go z kolejną wiadomością:

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

Nie używaj ponownie jednego identyfikatora konwersacji dla niezwiązanych ze sobą odwiedzających. Utwórz nową konwersację, pomijając conversationId (lub przekazując null). Identyfikator grupuje zapisane wiadomości, lecz bieżący generator nie przekazuje wcześniejszych tur do modelu — pytania uzupełniające muszą zawierać własny kontekst.

Obsługa błędów

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 zawiera status HTTP, a code jest opcjonalny. Błędy sieciowe nie są opakowywane. sendMessage() przyjmuje tylko message, opcjonalne conversationId i idempotencyKey: nie obsługuje sourceUrl, sourcePath, locale ani opcji modelu. Ogranicz wiadomość do 2 000 znaków po trimie i dla retry zachowaj ten sam unikalny idempotencyKey.

Ponownie wykorzystaj ustawienia projektu i tłumaczenia

SDK udostępnia również metody getWidgetConfig() i getWidgetTranslations(locale). Obsługują one klientów, którzy chcą odtworzyć ustawienia projektu i zlokalizowane etykiety hostowanego widżetu:

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

W pełni niestandardowy interfejs może je pominąć. Przechowuj conversationId każdego odwiedzającego w jego przeglądarce lub stanie sesji; nigdy nie udostępniaj jednego globalnego identyfikatora konwersacji.

Następne kroki

• Wolisz utrzymywany interfejs bez budowania? Zainstaluj widget.js.
• Dostosuj hostowany interfejs w sekcji Dostosowywanie hostowanego widżetu.
• Przed uruchomieniem przetestuj ograniczenia originów, odpowiedzi awaryjne, cytowania i działanie na urządzeniach mobilnych, korzystając z listy kontrolnej przed uruchomieniem.