JavaScript SDK

:::note Stav verzí Vydané npm SDK 0.1.4 validuje baseUrl, obaluje nečitelné tělo odpovědi a config po HTTP 400 opakuje pouze jednou. S widget.js v15 podporuje remove()/window.ChattyBox.destroy() teardown; headless sendMessage() se automaticky neopakuje. :::

Balíček npm je doporučený způsob integrace ChattyBoxu. Nakonfigurujte jednoho klienta a načtěte spravovaný plovoucí widget z trvalého rozvržení prohlížeče, 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();

// Loader ponechte po celou životnost stránky včetně navigace SPA.

mountWidget() volejte až po vytvoření document.body, ne při renderování ani SSR. Widget se přidá pod document.body, ne do komponenty; { locale: 'fr' } funguje pouze při povoleném přepsání skriptem a jen při inicializaci.

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 a vytvořte klíč pro prohlížeč. Omezení přesných originů je volitelné.
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();

// Pro záměrný teardown použijte widget.remove().

mountWidget() vrací handle před připraveností skriptu či UI. Ve vydaném SDK 0.1.4 stejné mounty sdílí skript a každý handle drží referenci: remove() je idempotentní a teprve poslední handle zruší inicializaci, retry i probíhající chat a pak odstraní UI, styly, odkazy na fonty, skript i globální API. Jiný klíč, API URL, scriptUrl, locale nebo debug volba se odmítne, dokud existují handly. S widget.js v15 provede stejný teardown window.ChattyBox.destroy(). Nekombinujte SDK s GTM, pluginem ani druhým loaderem.

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	Odpověď nebo fallback; vykreslujte jako text či bezpečný Markdown.
conversationId	string	Identifikátor používaný k pokračování této konverzace.
sources	string[]	URL zdrojů; fallback může být prázdný.

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. Vynechání nebo null vytvoří novou konverzaci. ID jen seskupuje uložené zprávy: aktuální generátor nepředává dřívější tahy modelu, proto musí mít doplňující otázka vlastní kontext.

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 a code je volitelný; síťové chyby se neobalují. sendMessage() přijímá jen message, volitelné conversationId a idempotencyKey, nikoli sourceUrl, sourcePath, locale ani volby modelu. Omezte zprávu na 2 000 znaků a pro retry ponechte stejný unikátní idempotencyKey.

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.