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 klucz publiczny i adres URL API, a następnie załaduj utrzymywany pływający widżet z trwałego układu przeglądarki albo użyj metod headless z własnymi komponentami. Opublikowane SDK 0.1.4 zawiera poprawki cyklu życia i deklaracji dla ścisłego NodeNext. Pełne usuwanie widżetu wymaga również zaktualizowanego widget.js; przy samodzielnym hostowaniu zaktualizuj ten plik osobno.
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.
Nazwy import.meta.env.PUBLIC_* w przykładach są poglądowe. Użyj konwencji publicznej konfiguracji swojego frameworka, np. import.meta.env.VITE_* w Vite lub process.env.NEXT_PUBLIC_* w Next.js. W Node.js odczytaj i zweryfikuj wartości process.env.
Uzyskaj konfigurację publiczną
- Utwórz projekt i zindeksuj treści.
- Przetestuj reprezentatywne pytania w Przetestuj chatbota.
- W Instalacja → Klucze i domeny sprawdź lub utwórz publiczny klucz przeglądarkowy i sprawdź jego originy. Klucze bez ograniczeń działają z dowolnego originu; klucz przygotowany dla witryny może już być ograniczony.
- W Instalacja → Instalacja na stronie wpisz adres URL witryny HTTP(S), wybierz odpowiedni klucz i skopiuj adres URL API widżetu z wygenerowanego fragmentu. Lista oferuje niewygasłe klucze bez ograniczeń lub dozwolone dla originu tego adresu; aby wybrać ograniczony klucz, wpisz jego dozwolony origin. Sprawdź ograniczenia przez Zarządzaj kluczami i dozwolonymi domenami. Jeśli formularz jest niedostępny, wykonaj najpierw wskazany w panelu krok konfiguracji.
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. Jako opcjonalne dodatkowe zabezpieczenie użyj Instalacja → Klucze i domeny → Edytuj originy, aby włączyć ograniczenie i wskazać dokładne originy. Ograniczenia nie uwierzytelniają odwiedzających. Pakiet jest klientem ESM dla współczesnych aplikacji Node.js i przeglądarek udostępniających fetch.
Ograniczenia porównują znormalizowany schemat, nazwę hosta i port, a nie ścieżki ani subdomeny z symbolem wieloznacznym. API używa nagłówka Origin, a gdy go nie ma — originu z Referer. Brak originu lub niedozwolony origin przy ograniczonym kluczu zwraca 401 Invalid API key, tak samo jak nieprawidłowy lub wygasły klucz. Node.js fetch nie wysyła automatycznie żadnego z tych nagłówków przeglądarki. Kontrola originu nie jest uwierzytelnianiem i nie zapobiega fałszowaniu nagłówków przez klienta spoza przeglądarki.
Konstruktor i eksporty
new Chattybox(options) przyjmuje wymagany, niepusty publiczny klucz apiKey i wymagany, niepusty baseUrl. W SDK 0.1.4 adres musi być bezwzględnym adresem HTTP(S) bez danych uwierzytelniających, parametrów zapytania i fragmentu. Opcjonalny fetch musi być funkcją zgodną z fetch; w przeciwnym razie używany jest globalny fetch. Skopiuj adres HTTP API widżetu z fragmentu instalacji na stronie, a nie adres panelu ani adres klienta Convex .cloud. SDK usuwa końcowe ukośniki, a następnie końcowe /chat; klient udostępnia właściwości tylko do odczytu apiKey i znormalizowany baseUrl.
Konstruktor zgłasza zwykły Error, gdy opcje nie są obiektem lub ich brakuje, apiKey albo baseUrl nie jest niepustym ciągiem, podany fetch nie jest funkcją lub baseUrl nie spełnia powyższych wymagań. Pakiet eksportuje Chattybox, ChattyboxError oraz typy ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions i HostedWidgetHandle. Nie zawiera komponentu ani hooków Reacta. Pakiet IIFE ./browser udostępnia dwa konstruktory w window.ChattyboxSDK; samo jego załadowanie nie montuje interfejsu.
Zamontuj hostowany widżet z poziomu kodu
Użyj tej opcji, aby inicjalizować utrzymywany pływający interfejs ChattyBox z 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, a ostatni handle wysyła sygnał usunięcia i usuwa skrypt. Z hostowanym widget.js v15 sygnał anuluje inicjalizację, ponowienia oraz trwający chat i usuwa UI, style, linki fontów oraz 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ą.
mountWidget(options?) zwraca uchwyt synchronicznie. options.scriptUrl domyślnie wskazuje https://chattybox.ai/widget.js; zmieniaj go tylko na zaufany loader podglądowy lub hostowany samodzielnie. Niepuste options.locale ustawia data-locale, jeśli projekt dopuszcza allowLocaleOverride; options.debug ustawia data-debug="true" tylko dla wartości truthy. handle.element wskazuje dodany lub ponownie użyty element skryptu.
Usuń każdy pasujący uchwyt przy celowym zakończeniu działania lub wycofaniu zgody. Teardown nie cofnie żądania już przetworzonego przez serwer. Przy zwykłej nawigacji po stronie klienta zachowaj loader w trwałej powłoce. SDK wykrywa tylko oznaczony skrypt, nie każdy ręcznie dodany loader. Własny fetch konstruktora służy tylko metodom headless i nie jest przekazywany hostowanemu widżetowi. SDK nie zapewnia obietnicy gotowości, docelowego kontenera ani reaktywnej aktualizacji locale; przed zmianą projektu lub locale usuń wszystkie wcześniejsze uchwyty.
Hostowany loader v15 ponawia błędy transportu, przerwany odczyt poprawnej odpowiedzi, ograniczenia częstotliwości i błędy serwera z tą samą treścią oraz kluczem idempotencji. Wykonuje najwyżej 10 prób i nie planuje automatycznej próby po upływie 30 sekund; czytelne opóźnienie Retry-After wlicza się do tego okresu. Po wyczerpaniu prób ponowienie wiadomości używa tego samego logicznego żądania; nowe pytanie rozpoczyna nowe żądanie. Niepoprawny JSON lub struktura poprawnej odpowiedzi oznaczają końcowy błąd protokołu, nie automatyczne ponowienie. Odpowiedzi między originami muszą udostępniać Retry-After przez Access-Control-Expose-Headers. Sprawdź wersję wdrożonego loadera.
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 fragmentu w Instalacja na stronie. 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 oczyszczony Markdown, a nie surowy HTML. |
conversationId | string | Identyfikator używany do kontynuowania tej konwersacji. |
sources | string[] | Adresy źródeł; fallback może mieć pustą listę. Przed renderowaniem linków sprawdź, czy adresy są HTTP(S). |
providerError | string (opcjonalne w aktualnym kodzie źródłowym) | Ustrukturyzowany kod błędu zwracany przy awarii dostawcy. Nie występuje przy zwykłych odpowiedziach ani skonfigurowanych komunikatach fallback; nieznane kody traktuj jak ogólny błąd. |
productFallback | 'no_context_ui' | 'no_context_question' (opcjonalne w aktualnym kodzie źródłowym) | Oznacza produktowy komunikat bez kontekstu i sposób wyboru jego języka; szczegóły poniżej. |
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; przy tym samym conversationId model otrzymuje do 12 ostatnich zapisanych wiadomości, każdą przyciętą do 2 000 znaków. To ograniczony kontekst, nie pełny zapis ani trwała pamięć; w razie potrzeby przypomnij starsze szczegóły.
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(input) zwraca Promise<ChatResponse>. SendMessageInput przyjmuje message: string oraz opcjonalne conversationId: string | null i idempotencyKey: string. Aktualny kod źródłowy obsługuje też opcjonalne uiLocale: string; tej opcji nie ma w opublikowanym SDK 0.1.4. SDK wysyła publiczny klucz API w treści JSON, ale nie przekazuje kontekstu strony (sourceUrl ani sourcePath) ani opcji modelu. Przed wysłaniem sprawdź, czy wiadomość nie jest pusta, i ogranicz jej długość po trimie do 2 000 znaków. Backend egzekwuje ten limit, ale jego wewnętrzne błędy walidacji są obecnie zwracane jako ogólne błędy HTTP 500.
W aktualnym kodzie źródłowym można przekazać na przykład chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). SDK przekazuje podaną wartość locale bez zmian i pomija ją, gdy nie została podana albo ma wartość undefined; nie wykrywa locale automatycznie. Serwer sprawdza wartość i normalizuje ją do obsługiwanego języka bazowego. Nieprawidłowa lub nieobsługiwana wartość powoduje HTTP 400 Invalid uiLocale, zamiast cichego przejścia na inny język. Locale to kontekst prezentacji dostarczany przez wywołującego, a nie mechanizm uwierzytelniania ani autoryzacji.
Rozpoznany sygnał języka pytania ma pierwszeństwo przed uiLocale przy wyborze języka komunikatów fallback należących do produktu. Jeśli wykrywanie jest niejednoznaczne albo opiera się wyłącznie na heurystyce angielskiego tekstu ASCII, uiLocale może określić ich język; jeśli brakuje obu sygnałów, stosowane są domyślne ustawienia produktu. Fallback skonfigurowany przez projekt jest używany bez zmian zamiast produktowego fallbacku bez kontekstu. uiLocale nie tłumaczy tekstu fallbacku autora projektu ani nie zmienia odpowiedzi wygenerowanej przez AI; nie gwarantuje też jakości odpowiedzi ani jej języka.
API widgetu/czatu w aktualnym kodzie źródłowym dodaje productFallback wyłącznie do produktowych odpowiedzi bez kontekstu; dostępność zależy od wersji backendu, a nie SDK. no_context_ui oznacza, że język fallbacku wybrano na podstawie locale interfejsu lub domyślnego locale albo nie udało się go ustalić; niestandardowy interfejs może ponownie zlokalizować komunikat, korzystając z bieżącego wpisu message.noContext w katalogu. no_context_question oznacza, że istniejący klasyfikator rozpoznał język pytania; zachowaj zwrócony tekst komunikatu. Nie dowodzi to, że język został rozpoznany poprawnie. Znacznik nie występuje przy własnych komunikatach fallback, zwykłych odpowiedziach, błędach dostawcy ani odpowiedziach ze starszych wersji. Nie wnioskuj o pochodzeniu komunikatu na podstawie zgodności jego treści z tekstem fallbacku ani braku znacznika; ignoruj nieznane wartości znacznika productFallback.
Opublikowane SDK 0.1.4 nie deklaruje productFallback w ChatResponse, ale przekazuje to pole w zwracanym obiekcie JSON, jeśli dostarczy je backend. Przed użyciem bezpiecznie zawęź jego wartość. Nie ma ogólnego pola wasAnswered ani pola statusu fallbacku, więc nie twórz ustrukturyzowanego wyniku oznaczającego, że pytanie pozostało bez odpowiedzi.
sendMessage() nie zapewnia strumieniowania, automatycznych ponowień, limitu czasu, opcji AbortSignal, przechowywania ani stanu interfejsu. Własny fetch może zapewnić odpowiednią politykę transportu. Brak automatycznych ponowień dotyczy czatu headless: SDK 0.1.4 ponawia tylko getWidgetConfig() raz po HTTP 400, a hostowany v15 ponawia początkowe żądania GET.
Bezpieczne ponawianie
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.
Przypisz unikalny idempotencyKey każdej logicznej wiadomości i zachowaj dokładne dane wejściowe do ponowienia, w tym pierwotny conversationId. SDK wysyła klucz jako nagłówek Idempotency-Key, ale nie tworzy go ani nie ponawia żądań za Ciebie.
Przy ponawianiu zachowaj ten sam idempotencyKey oraz dokładnie te same dane wejściowe, w tym pierwotne uiLocale i informację, czy zostało pominięte. Aktualny serwer uwzględnia znormalizowane locale w odcisku żądania. Klucz jest przypisany do projektu, musi mieć 1–128 znaków i pasować do [A-Za-z0-9][A-Za-z0-9._:-]*. Identyczne zakończone żądanie można odtworzyć, otrzymując pierwotny zapisany tekst wiadomości i znacznik, jeśli występuje, bez ponownego wykonywania żądania; zmienione dane, trwające żądanie lub błąd terminalny mogą zwrócić 409. Nie ponawiaj w ciemno każdego błędu 409 ani nie generuj nowego klucza po niejednoznacznym błędzie transportu.
Odtworzenie nie jest trwałe: rekordy zakończone i nieudane wygasają po 24 godzinach od rezerwacji, natomiast oczekujące nie są zwalniane wyłącznie z upływem czasu. Ponowienie po wygaśnięciu rekordu końcowego może wykonać żądanie ponownie. Ogranicz czas ponawiania i sprawdzaj utrzymujące się konflikty zamiast zakładać nieograniczoną deduplikację.
ChattyboxError.code występuje tylko wtedy, gdy API zwróci ciąg code; większość obecnych błędów API widżetu go nie zawiera. Odpowiedzi inne niż 2xx, niepusty ciąg error nawet przy HTTP 200, niepoprawny JSON i JSON niebędący obiektem powodują ChattyboxError. SDK 0.1.4 opakowuje też nieczytelną treść odpowiedzi kodem RESPONSE_BODY_READ_FAILED. Poprawne obiekty JSON są rzutowane na zadeklarowany typ bez walidacji każdego pola. Błędy sieciowe i inne błędy fetch przechodzą bez zmian.
Typowe statusy to 400 dla niepoprawnych danych lub nieobsługiwanej locale tłumaczeń, 401 dla błędu klucza lub originu, 403 dla wyłączonego widżetu projektu (również w czacie headless), 409 dla konfliktu idempotencji, 413 dla treści czatu większej niż 65 536 bajtów, 429 dla ograniczenia częstotliwości i 500 dla błędów wewnętrznych. SDK nie udostępnia nagłówków odpowiedzi w wyniku ani błędzie.
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.
getWidgetConfig() zwraca Promise<WidgetConfig> i uwierzytelnia żądanie nagłówkiem Authorization: Bearer. SDK 0.1.4 tylko po HTTP 400 ponawia je dokładnie raz z zakodowanym kluczem w parametrze URL, na wypadek usunięcia nagłówka przez pośrednika; nie ponawia innych statusów. WidgetConfig to Record<string, unknown> z opcjonalnymi typowanymi polami dotyczącymi włączenia, kolorów, pozycji, tytułu, powitania, brandingu, ikon i języka (localeMode: 'auto' | 'fixed', defaultLocale: string, allowLocaleOverride: boolean). Przed użyciem zawęź pozostałe nieznane pola. Aktualne pola i wartości domyślne opisano w dostosowywaniu hostowanego widżetu. Pomyślne żądanie konfiguracji oznacza projekt jako mający zainstalowany widżet, nawet jeśli własny klient go nie renderuje.
Aktualne typy w kodzie źródłowym SDK definiują w WidgetConfig opcjonalne pola headerTitleIsDefault?: boolean i welcomeMessageIsDefault?: boolean. Każda flaga opisuje odpowiadający jej tekst: true oznacza zlokalizowany domyślny tekst produktu, a false — tekst niestandardowy, który należy zachować. Brak flagi, również w starszych odpowiedziach, oznacza, że pochodzenie tekstu jest nieznane; nigdy nie próbuj ustalać go przez porównanie tekstu z wartością domyślną. Dostępność tych pól zależy od wersji backendu, a nie SDK. Opublikowane SDK 0.1.4 nie deklaruje tych flag jako wartości logicznych, ale typ Record<string, unknown> oraz niezmieniony obiekt JSON odpowiedzi pozwalają bezpiecznie zawęzić ich typ, jeśli są obecne. Pomyślne odpowiedzi nie są walidowane ani konwertowane pole po polu.
getWidgetTranslations(locale) zwraca Promise<WidgetTranslations> z translations: Record<string, string>, dir: 'ltr' | 'rtl' i wybranym przez serwer locale: string. Ten publiczny endpoint nie korzysta z klucza API ani ustawień języka projektu. Podaj jeden z kodów en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy lub cs. SDK koduje locale w adresie URL, ale jej nie normalizuje: fr-CA i FR zwracają 400, inaczej niż normalizacja regionalna hostowanego widżetu. Pusty ciąg wybiera angielski na serwerze. Wszystkie obecne katalogi są LTR i można je przechowywać w pamięci podręcznej przez godzinę.
We własnym interfejsie samodzielnie ustal locale, uwzględnij allowLocaleOverride i tryb stały lub automatyczny projektu, jeśli odtwarzasz zachowanie hostowanego widżetu, oraz zapewnij wartości zastępcze dla brakujących kluczy tłumaczeń. Ustawienia te sterują etykietami UI; klient headless z aktualnego kodu źródłowego może osobno podać uiLocale dla produktowych komunikatów fallback. Żaden z tych mechanizmów nie gwarantuje jakości ani języka odpowiedzi wygenerowanej przez AI.
Następne kroki
- Wolisz utrzymywany interfejs bez budowania? Zainstaluj
widget.js. - Dostosuj hostowany interfejs w sekcji Dostosowywanie hostowanego widżetu.
- Przed uruchomieniem przetestuj odpowiedzi awaryjne, cytowania i działanie na urządzeniach mobilnych, korzystając z listy kontrolnej przed uruchomieniem. Jeśli włączysz ograniczenie originów, przetestuj także dokładne originy.