JavaScript SDK

Pakiet npm to zalecany sposób integracji z ChattyBox. Zaimportuj jednego klienta do aplikacji, skonfiguruj jego klucz publiczny i adres URL API, a następnie zamontuj utrzymywany interfejs tam, gdzie aplikacja go potrzebuje, 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();

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

Wywołuj mountWidget() w kodzie przeglądarki, w komponencie lub layoucie, w którym utrzymywany interfejs ma być dostępny. Możesz przekazać { locale: 'fr' }, aby ustawić lokalizację dla konkretnej trasy.

Uzyskaj konfigurację publiczną

1. Utwórz projekt i zindeksuj treści.
2. Przetestuj reprezentatywne pytania w panelu.
3. Otwórz Public Keys, utwórz klucz przeglądarkowy i ogranicz jego dozwolone originy.
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();

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

Ładuje utrzymywany interfejs raz i nie jest dostępny podczas renderowania po stronie serwera.

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	Wygenerowana odpowiedź.
conversationId	string	Identyfikator używany do kontynuowania tej konwersacji.
sources	string[]	Adresy URL źródeł pobranych na potrzeby odpowiedzi.

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 w ich pierwszej wiadomości.

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. code występuje, gdy API zwraca ustrukturyzowany kod błędu.

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.