JavaScript SDK

Balíček npm je doporučený způsob integrace ChattyBoxu. Importujte do aplikace jednoho klienta, nakonfigurujte jeho veřejný klíč a URL API a poté připojte spravované rozhraní tam, kde ho aplikace potřebuje, nebo použijte headless metody s vlastními komponentami.

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

mountWidget() volejte v kódu prohlížeče z komponenty nebo layoutu, kde má být spravované rozhraní dostupné. Pro konkrétní jazyk trasy můžete předat { locale: 'fr' }.

Získejte veřejnou konfiguraci

1. Vytvořte projekt a indexujte svůj obsah.
2. Otestujte reprezentativní otázky v řídicím panelu.
3. Otevřete Public Keys, vytvořte klíč pro prohlížeč a omezte jeho povolené originy.
4. Otevřete Embed, vyberte tento klíč a zkopírujte URL API widgetu zobrazenou spolu s vygenerovaným úryvkem.

Veřejné klíče API widgetu jsou určeny k zobrazení v kódu prohlížeče. Identifikují projekt, ale nejsou přihlašovacími údaji pro jeho správu. Klíče pro prohlížeč omezte na domény, které smějí volat váš chatbot. Balíček je klient ESM pro současné aplikace Node.js a prohlížeče, které poskytují fetch.

Připojte hostovaný widget z kódu

Použijte tuto možnost, když chcete spravované rozhraní ChattyBoxu a zároveň řídit, kde se z kódu aplikace připojí:

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

Načte spravované rozhraní jednou a při vykreslování na serveru není k dispozici.

Vytvořte vlastní rozhraní

Níže uvedené headless metody použijte, když vaše aplikace spravuje seznam zpráv, vstup, stavy načítání a chyb, citace a přístupnost.

Odeslání zprávy

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

Nastavte PUBLIC_CHATTYBOX_API_URL na přesnou URL API widgetu z karty Embed. SDK přijímá kořen nasazení i URL končící na /chat.

Odpověď obsahuje:

Pole	Typ	Popis
message	string	Vygenerovaná odpověď.
conversationId	string	Identifikátor používaný k pokračování této konverzace.
sources	string[]	URL zdrojů načtených pro odpověď.

Pokračování konverzace

Vrácené ID konverzace uchovávejte ve stavu uživatelského rozhraní a odešlete je s další zprávou:

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

Jedno ID konverzace znovu nepoužívejte pro nesouvisející návštěvníky. Novou konverzaci vytvoříte tak, že při jejich první zprávě vynecháte conversationId.

Zpracování chyb

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 obsahuje stav HTTP. code je přítomen, když API vrátí strukturovaný kód chyby.

Opětovné použití nastavení projektu a překladů

SDK poskytuje také getWidgetConfig() a getWidgetTranslations(locale). Tyto metody podporují klienty, kteří chtějí napodobit nastavení projektu a lokalizované popisky hostovaného widgetu:

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

Plně vlastní rozhraní je používat nemusí. ID conversationId každého návštěvníka uchovávejte v jeho prohlížeči nebo stavu relace; nikdy nesdílejte jedno globální ID konverzace.

Další kroky

• Dáváte přednost spravovanému rozhraní bez sestavení? Nainstalujte widget.js.
• Hostované rozhraní přizpůsobte v části Přizpůsobení hostovaného widgetu.
• Před spuštěním otestujte omezení originů, záložní odpovědi, citace a chování na mobilních zařízeních pomocí kontrolního seznamu před spuštěním.