Přejít na hlavní obsah

JavaScript SDK

:::note Stav verzí Vydané npm SDK 0.1.4 obsahuje opravy životního cyklu a deklarací pro striktní NodeNext, 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. Úplné odstranění widgetu vyžaduje aktualizovaný hostovaný widget.js; při vlastním hostování je třeba tento soubor aktualizovat samostatně. :::

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.

Názvy import.meta.env.PUBLIC_* v příkladech jsou pouze ilustrativní. Použijte konvenci veřejné konfigurace svého frameworku, například import.meta.env.VITE_* ve Vite nebo process.env.NEXT_PUBLIC_* v Next.js. V Node.js hodnoty process.env načtěte a ověřte.

Získejte veřejnou konfiguraci​

  1. Vytvořte projekt a indexujte svůj obsah.
  2. Otestujte reprezentativní otázky v části Otestovat chatbota.
  3. V části Instalace → Klíče a domény zkontrolujte nebo vytvořte veřejný klíč pro prohlížeč a ověřte jeho originy. Klíče bez omezení fungují ze všech originů; klíč připravený pro web již může být omezený.
  4. V části Instalace → Instalace na web zadejte HTTP(S) URL webu, vyberte vhodný klíč a zkopírujte URL API widgetu z vygenerovaného úryvku. Výběr nabízí neexpirované klíče bez omezení nebo povolené pro origin této URL; pro omezený klíč zadejte jeho povolený origin. Omezení ověřte přes Spravovat klíče a povolené domény. Není-li formulář dostupný, nejprve dokončete krok nastavení uvedený v dashboardu.

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. Jako volitelné dodatečné zabezpečení zapněte omezení a zadejte přesné originy v části Instalace → Klíče a domény → Upravit originy. Omezení neověřuje návštěvníky. Balíček je klient ESM pro současné aplikace Node.js a prohlížeče, které poskytují fetch.

Omezení porovnává normalizované schéma, název hostitele a port, nikoli cesty nebo zástupné subdomény. API používá hlavičku Origin, případně origin z Referer. Chybějící nebo nepovolený origin u omezeného klíče vrátí HTTP 401 Invalid API key, stejně jako neplatný nebo expirovaný klíč. Node.js fetch neposílá tyto prohlížečové hlavičky automaticky. Kontrola originu není autentizace a nezabrání klientovi mimo prohlížeč hlavičky podvrhnout.

Konstruktor a exporty​

new Chattybox(options) přijímá ChattyboxOptions: povinný neprázdný veřejný klíč apiKey, povinný neprázdný baseUrl a volitelnou implementaci fetch; jinak použije globální fetch. SDK 0.1.4 vyžaduje absolutní HTTP(S) URL bez přihlašovacích údajů, parametrů dotazu a fragmentu. Zkopírujte URL API widgetu z instalačního úryvku, nikoli URL dashboardu nebo klientskou URL Convex .cloud. Odstraní se koncová lomítka a následně koncové /chat. Klient zpřístupňuje apiKey a normalizovaný baseUrl pouze pro čtení.

Konstruktor vyhodí běžný Error, pokud volby chybí nebo nejsou objektem, apiKey či baseUrl chybí, není řetězec nebo je prázdný, předané fetch není funkce, nebo baseUrl není platná absolutní HTTP(S) URL bez uvedených zakázaných částí.

Balíček exportuje Chattybox, ChattyboxError a typy ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions a HostedWidgetHandle. Neobsahuje komponentu ani hooky pro React. IIFE balíček ./browser zpřístupňuje oba konstruktory přes window.ChattyboxSDK; samotné načtení rozhraní nepřipojí.

Připojte hostovaný widget z kódu​

Použijte tuto možnost, chcete-li z kódu aplikace inicializovat spravované plovoucí rozhraní ChattyBoxu:

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 poslední handle vyšle signál odstranění a odstraní skript. S hostovaným widget.js v15 signál zruší inicializaci, retry i probíhající chat a odstraní UI, styly, odkazy na fonty 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.

mountWidget(options?) vrací HostedWidgetHandle synchronně. Volba scriptUrl má výchozí hodnotu https://chattybox.ai/widget.js; měňte ji jen pro důvěryhodný náhledový nebo vlastnoručně hostovaný loader. Neprázdné locale nastaví data-locale, které musí pravidla projektu povolit; debug nastaví data-debug="true" pouze při pravdivé hodnotě. handle.element je vložený nebo znovu použitý HTMLScriptElement.

Při úklidu komponenty nebo odvolání souhlasu odeberte každý odpovídající handle. Teardown nemůže vrátit požadavek již zpracovaný serverem. Při běžné navigaci ponechte loader v trvalém shellu. SDK nerozpoznává ručně vložené loadery bez markeru. Vlastní fetch konstruktoru používají jen headless metody, nikoli hostovaný widget. SDK nenabízí promise připravenosti, cílový kontejner ani reaktivní API pro změnu locale.

Hostovaný loader v15 opakuje chyby přenosu, přerušené čtení úspěšné odpovědi, probíhající požadavky, omezení rychlosti a chyby serveru se stejným tělem a klíčem idempotence. Provede nejvýše 10 pokusů a nenaplánuje další automatické opakování po 30 sekundách; čitelná prodleva Retry-After se do tohoto limitu započítává. Po vyčerpání pokusů Retry message znovu použije tentýž logický požadavek; nová otázka zahájí nový. Neplatný JSON nebo neplatný formát úspěšné odpovědi je konečná chyba protokolu bez automatického opakování. Pro čtení Retry-After napříč originy musí API tuto hlavičku zpřístupnit přes Access-Control-Expose-Headers.

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 úryvku v části Instalace na web. SDK přijímá kořen nasazení i URL končící na /chat.

Odpověď obsahuje:

PoleTypPopis
messagestringOdpověď nebo fallback; vykreslujte jako text či sanitizovaný Markdown, nikoli jako surové HTML.
conversationIdstringIdentifikátor používaný k pokračování této konverzace.
sourcesstring[]URL zdrojů; u fallbacku může být seznam prázdný. Před vykreslením odkazů ověřte, že jde o HTTP(S) URL.
providerErrorstring (volitelné v aktuálním zdrojovém kódu)Strukturovaný kód chyby vracený při selhání poskytovatele. U běžných odpovědí a nakonfigurovaných fallback zpráv se nevyskytuje; neznámé kódy považujte za obecnou chybu.
productFallback'no_context_ui' | 'no_context_question' (volitelné v aktuálním zdrojovém kódu)Označuje produktovou zprávu bez kontextu a způsob výběru jejího jazyka; podrobnosti níže.

Headless sendMessage() neposkytuje streaming, automatická opakování, timeout, volbu AbortSignal, úložiště ani stav UI. Vlastní implementace fetch může zajistit pravidla přenosu. Toto omezení opakování se týká headless chatu: SDK 0.1.4 zopakuje pouze getWidgetConfig() jednou po HTTP 400 a hostovaný v15 opakuje úvodní GET požadavky.

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í conversationId nebo null vytvoří novou konverzaci. ID seskupuje uložené zprávy; při stejném conversationId model dostane až 12 nedávných uložených zpráv, každou zkrácenou na 2 000 znaků. Jde o omezený kontext, nikoli úplný přepis nebo trvalou paměť; starší podrobnosti podle potřeby zopakujte.

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(input) vrací Promise<ChatResponse>. SendMessageInput přijímá message: string a volitelné conversationId: string | null a idempotencyKey: string. Aktuální zdrojový kód podporuje také volitelné uiLocale: string; ve vydaném SDK 0.1.4 tato možnost není dostupná. SDK posílá veřejný klíč API v těle JSON, ale neposílá kontext stránky (sourceUrl ani sourcePath) ani volby modelu. Před odesláním ověřte, že zpráva není prázdná, a omezte její délku po oříznutí mezer na 2 000 znaků. Backend tento limit vynucuje, ale jeho interní chyby validace se nyní vracejí jako obecné chyby HTTP 500.

V aktuálním zdrojovém kódu lze například předat chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). SDK předanou hodnotu locale přeposílá beze změny a vynechá ji, pokud nebyla zadána nebo má hodnotu undefined; locale samo nedetekuje. Server hodnotu ověří a normalizuje na podporovaný základní jazyk. Neplatná nebo nepodporovaná hodnota vrátí HTTP 400 Invalid uiLocale, místo aby tiše přešla na jiný jazyk. Locale je kontext prezentace dodaný volajícím, nikoli prostředek autentizace či autorizace.

Rozpoznaný jazykový signál z otázky má přednost před uiLocale při určování jazyka produktových fallback zpráv. Pokud je detekce neprůkazná nebo se opírá pouze o heuristiku anglického textu ASCII, může jazyk těchto zpráv určit uiLocale; pokud chybí oba signály, použijí se výchozí nastavení produktu. Fallback nakonfigurovaný projektem se použije beze změny místo produktového fallbacku bez kontextu. uiLocale nepřekládá fallback text napsaný autorem projektu ani nemění odpovědi vygenerované AI; nezaručuje ani kvalitu odpovědi či její jazyk.

Aktuální API widgetu/chatu přidává productFallback pouze k produktovým odpovědím bez kontextu; dostupnost závisí na verzi backendu, nikoli SDK. no_context_ui znamená, že jazyk fallbacku byl vybrán podle locale rozhraní nebo výchozího locale, případně nebyl určen; vlastní rozhraní jej může znovu lokalizovat podle aktuální položky message.noContext v katalogu. no_context_question znamená, že stávající klasifikátor rozpoznal jazyk otázky; zachovejte vrácený text zprávy. Neznamená to, že jazyk byl rozpoznán správně. Značka chybí u vlastních fallback zpráv, běžných odpovědí, chyb poskytovatele a odpovědí starších verzí. Nepředpokládejte původ zprávy podle shody jejího textu s fallback textem ani podle absence značky; neznámé hodnoty značky productFallback ignorujte.

Vydané SDK 0.1.4 v ChatResponse pole productFallback nedeklaruje, ale pokud jej backend poskytne, předá je ve vráceném objektu JSON. Před použitím hodnotu bezpečně zúžte. Neexistuje obecné pole wasAnswered ani pole stavu fallbacku, proto nevymýšlejte strukturovaný výsledek označující nezodpovězenou otázku.

Při opakování požadavku zachovejte stejný idempotencyKey a přesně stejný vstup, včetně původního uiLocale a toho, zda bylo vynecháno. Aktuální server zahrnuje normalizované locale do otisku požadavku. Klíč je vázaný na projekt, musí mít 1–128 znaků a odpovídat [A-Za-z0-9][A-Za-z0-9._:-]*. Totožný dokončený požadavek lze přehrát s původním uloženým textem zprávy a značkou (pokud existuje), aniž by se požadavek znovu zpracoval; změněný vstup, probíhající požadavek nebo konečná chyba mohou vrátit 409. Neopakujte naslepo každou chybu 409 a po nejednoznačné chybě přenosu nevytvářejte nový klíč.

Pro každou logickou zprávu zvolte unikátní idempotencyKey a při opakování zachovejte i původní conversationId. SDK klíč odesílá v hlavičce Idempotency-Key, ale samo ho nevytváří ani požadavek neopakuje. Přehrání není trvalé: dokončené a neúspěšné záznamy expirují 24 hodin po rezervaci, zatímco čekající záznamy se neuvolňují pouze uplynutím času. Po expiraci konečného záznamu se požadavek může provést znovu. Omezte časové okno opakování a přetrvávající konflikty prošetřete.

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.

code v ChattyboxError je přítomen pouze tehdy, když API vrátí řetězcové code; většina aktuálních chyb widget API jej neobsahuje. Chybu vyvolají odpovědi mimo 2xx, neprázdné řetězcové error i při HTTP 200, neplatný JSON a JSON, který není objektem. SDK 0.1.4 obalí i nečitelné tělo odpovědi kódem RESPONSE_BODY_READ_FAILED. Úspěšné objekty JSON se přetypují bez běhové validace jednotlivých polí.

Mezi běžné stavy patří 400 pro neplatný vstup nebo nepodporované locale překladů, 401 pro chyby klíče či originu, 403 pro vypnutý widget projektu včetně headless chatu, 409 pro konflikty idempotence, 413 pro tělo chatu nad 65 536 bajtů, 429 při omezení rychlosti a 500 při interní chybě. SDK nezpřístupňuje hlavičky odpovědi ve výsledku ani v chybě.

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.

getWidgetConfig() vrací Promise<WidgetConfig> a používá Authorization: Bearer. SDK 0.1.4 po HTTP 400 přesně jednou zopakuje požadavek s URL-kódovaným klíčem v parametru dotazu pro případ, že prostředník odstranil hlavičku; při jiných stavech jej neopakuje. WidgetConfig je Record<string, unknown> s volitelnými typovanými poli pro zapnutí, barvy, pozici, texty, branding, ikony a nastavení locale (localeMode: 'auto' | 'fixed', defaultLocale: string, allowLocaleOverride: boolean). Další neznámá pole před použitím bezpečně zúžte. Aktuální pole a výchozí hodnoty serveru najdete v části Přizpůsobení hostovaného widgetu. Úspěšný požadavek na konfiguraci označí projekt jako projekt s nainstalovaným widgetem i tehdy, když vlastní klient žádný widget nevykreslí.

Aktuální zdrojové typy SDK definují ve WidgetConfig volitelná pole headerTitleIsDefault?: boolean a welcomeMessageIsDefault?: boolean. Každý příznak popisuje odpovídající text: true znamená lokalizovaný výchozí text produktu, zatímco false označuje vlastní text, který je třeba zachovat. Chybějící příznak, a to i ve starších odpovědích, znamená, že původ textu není znám; nikdy jej neodvozujte porovnáním textu s výchozí hodnotou. Dostupnost závisí na verzi backendu, nikoli SDK. Vydané SDK 0.1.4 tyto příznaky nedeklaruje jako booleany, ale typ Record<string, unknown> a nezměněná JSON odpověď umožňují jejich bezpečné zúžení, pokud jsou přítomné. Úspěšné odpovědi neprocházejí validací jednotlivých polí ani převodem typů.

getWidgetTranslations(locale) vrací Promise<WidgetTranslations> s translations: Record<string, string>, dir: 'ltr' | 'rtl' a serverem zvoleným locale: string. Endpoint je veřejný a nepoužívá API klíč ani jazykové nastavení projektu. Předejte jeden z kódů en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy nebo cs. SDK locale URL-kóduje, ale nenormalizuje: fr-CA a FR vrátí 400, na rozdíl od normalizace regionálních locale v hostovaném widgetu. Prázdný řetězec vybere na serveru angličtinu. Všechny současné katalogy používají směr LTR a lze je cachovat jednu hodinu.

Ve vlastním UI určete požadované locale sami, při napodobování hostovaného chování respektujte allowLocaleOverride a pevný či automatický režim projektu a zajistěte náhradní hodnoty pro chybějící klíče překladů. Tato nastavení řídí popisky UI; headless klient z aktuálního zdrojového kódu může samostatně předat uiLocale pro produktové fallback zprávy, jak je popsáno výše. Ani jedno nezaručuje kvalitu ani jazyk odpovědí generovaných AI.

Další kroky​