Hoppa till huvudinnehållet

JavaScript SDK

:::note Versionsstatus Det publicerade npm-SDK:t 0.1.4 validerar baseUrl, omsluter oläsbara response-bodies och försöker config HTTP 400 igen bara en gång. Med widget.js v15 stöder remove()/window.ChattyBox.destroy() teardown; headless sendMessage() försöker inte igen automatiskt. :::

npm-paketet är det rekommenderade sättet att integrera ChattyBox från applikationskod. Konfigurera dess offentliga nyckel och API-URL och ladda sedan den underhållna flytande widgeten från en beständig webbläsarlayout, eller använd headless-metoderna med egna komponenter.

Det publicerade SDK:t 0.1.4 innehåller livscykeländringarna och korrigeringarna av typdeklarationer för strikt NodeNext. Fullständig avveckling av widgeten kräver också en uppdaterad underhållen widget.js; självhostade installationer måste uppdatera den filen separat.

Snabbstart​

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

// Behåll laddaren under sidans livstid, även vid SPA-navigering.

Anropa mountWidget() efter att document.body finns, inte under rendering eller serverkörning. Den lägger en flytande widget under document.body, inte i komponenten. { locale: 'fr' } begär språk vid initiering och fungerar bara om projektet tillåter script-override. Miljövariabelnamnen i exemplen är illustrativa: använd ramverkets egna publika konvention.

Till exempel används import.meta.env.VITE_* i Vite och process.env.NEXT_PUBLIC_* i Next.js. I Node.js läser och validerar du i stället värden från process.env.

Hämta din offentliga konfiguration​

  1. Skapa ett projekt och indexera ditt innehåll.
  2. Testa representativa frågor i Testa chatbot.
  3. Under Installera → Nycklar & domäner, granska eller skapa en offentlig webbläsarnyckel och kontrollera dess origin-inställningar. Nycklar utan begränsningar fungerar från olika origins; en nyckel för en webbplats kan redan vara begränsad.
  4. Under Installera → Installation på webbplatsen, ange en HTTP(S)-webbadress, välj en lämplig nyckel och kopiera widgetens API-URL från kodfragmentet. Väljaren visar nycklar som inte har gått ut och som är obegränsade eller tillåtna för adressens origin. Ange en tillåten origin för en begränsad nyckel och granska begränsningarna via Hantera nycklar och tillåtna domäner. Om formuläret inte är tillgängligt slutför du först det förberedelsesteg som visas i instrumentpanelen.

Offentliga API-nycklar för widgeten är avsedda att visas i webbläsarkod. De identifierar ett projekt men är inte administrativa autentiseringsuppgifter. Under Installera → Nycklar & domäner → Redigera origins kan du valfritt aktivera en originbegränsning som extra skydd. Den matchar exakt schema, värd och port och är inte autentisering. Paketet är en ESM-klient för moderna Node.js- och webbläsarapplikationer som tillhandahåller fetch.

Begränsningarna matchar inte sökvägar eller wildcard-underdomäner. API:t använder förfrågans Origin eller, om den saknas, ursprunget i Referer. Saknat eller otillåtet ursprung för en begränsad nyckel ger 401 Invalid API key, precis som en ogiltig eller utgången nyckel. Node.js fetch skickar inte automatiskt någon av dessa webbläsarheaders. En klient utanför webbläsaren kan förfalska dem, så ursprungskontroller är inte autentisering.

Konstruktor och exporter​

new Chattybox(options) kräver en icke-tom offentlig widgetnyckel i apiKey och en icke-tom baseUrl. SDK 0.1.4 kräver en absolut HTTP(S)-URL utan autentiseringsuppgifter, querysträng eller fragment. En valfri fetch måste vara en funktion; annars används global fetch. Kopiera widgetens HTTP-API-URL från installationssnutten, inte instrumentpanelens URL eller en Convex .cloud-klient-URL. Avslutande snedstreck tas bort, följt av ett avslutande /chat. Klienten exponerar skrivskyddade apiKey och normaliserade baseUrl.

Konstruktorn kastar ett vanligt Error om alternativen är ogiltiga, nyckeln eller URL:en saknas eller är tom, fetch inte är en funktion eller URL:en inte uppfyller kraven ovan. Paketet exporterar Chattybox, ChattyboxError och typerna ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions och HostedWidgetHandle. Det innehåller inga React-komponenter eller hooks. IIFE-paketet ./browser exponerar konstruktorerna på window.ChattyboxSDK men monterar inget gränssnitt på egen hand.

Montera den hostade widgeten från kod​

Använd detta när du vill initiera ChattyBox underhållna flytande gränssnitt från applikationskod:

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({ locale: 'fr', debug: false });

mountWidget() returnerar ett handtag innan skriptet eller gränssnittet är redo. I det publicerade SDK:t 0.1.4 delar identiska monteringar skriptet och varje handtag äger en referens: anropa remove() för varje handtag. Med den hostade widget.js v15 avbryter det sista handtaget initiering, återförsök och pågående chatt och tar bort widgetens UI, stilar, typsnittslänkar, skript och globala API. Upprepad avveckling är säker. En annan nyckel, API-URL, scriptUrl, locale eller debug-inställning avvisas så länge handtag finns kvar. Med widget.js v15 utför window.ChattyBox.destroy() motsvarande avveckling. SDK:t har ingen särskild metod för reaktiv språkändring. Loadern i aktuell källkod följer däremot ändringar av skriptets data-locale; detta är loaderbeteende, inte ett SDK-API.

options.scriptUrl är som standard https://chattybox.ai/widget.js och bör bara ändras till en betrodd förhandsgransknings- eller självhostad loader. options.locale anger data-locale om värdet inte är tomt och projektets allowLocaleOverride tillåter det. options.debug anger data-debug="true" endast när värdet är truthy. handle.element är det infogade eller återanvända HTMLScriptElement-elementet. Avveckling kan inte ångra förfrågningar som servern redan har behandlat.

SDK:t upptäcker inte omarkerade manuella loaders. Välj en integrationsväg per sida och kombinera inte SDK-montering med ett plugin, en GTM-tagg eller ett separat skript. Konstruktorns anpassade fetch används bara av headless-metoderna, inte av den hostade widgeten. Det finns inget SDK-löfte om att widgeten är redo och inget mål för en behållare.

Den hostade v15-loadern försöker automatiskt igen vid transportfel, avbrutna lyckade svarskroppar, pågående svar, hastighetsbegränsning och serverfel, med samma förfrågningskropp och idempotensnyckel. Den gör högst 10 försök totalt och schemalägger inga automatiska återförsök efter 30 sekunder; läsbara Retry-After-fördröjningar räknas in i tidsfönstret. Efter att försöken har tagit slut återanvänder Retry message samma logiska förfrågan; en ny fråga startar en ny. Ogiltig JSON eller ett ogiltigt svarsformat i ett lyckat svar är ett terminalt protokollfel, inte ett automatiskt återförsök. API-svar över olika origins måste exponera Retry-After via Access-Control-Expose-Headers.

Bygg ett eget gränssnitt​

Använd headless-metoderna nedan när applikationen äger meddelandelista, inmatning, laddnings- och feltillstånd, källhänvisningar och tillgänglighet.

Skicka ett meddelande​

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

Ställ in PUBLIC_CHATTYBOX_API_URL på den exakta API-URL för widgeten som visas under Installation på webbplatsen. SDK:t accepterar både distributionsroten och en URL som slutar på /chat.

Svaret innehåller:

FältTypBeskrivning
messagestringSvarstext eller konfigurerat reservsvar; rendera säkert som text eller sanerad Markdown, inte som rå HTML.
conversationIdstringIdentifierare som används för att fortsätta denna konversation.
sourcesstring[]Käll-URL:er; kan vara tom för reservsvar. Validera HTTP(S)-URL:er innan länkar renderas.
productFallback'no_context_ui' | 'no_context_question' (valfritt, aktuell källkod)Identifierar produktens egen reservtext utan kontext och hur dess språk valdes; se nedan.
providerErrorstring (valfritt, aktuell källkod)Strukturerad felkod vid fel hos modellleverantören. Fältet saknas för vanliga svar och konfigurerade reservsvar. Behandla okända koder som generella fel.

sendMessage(input) returnerar Promise<ChatResponse>. SendMessageInput accepterar message: string, valfri conversationId: string | null och valfri idempotencyKey: string. Den aktuella källkoden accepterar även valfri uiLocale: string; den finns inte i det publicerade SDK:t 0.1.4. I den aktuella källkoden skickar SDK:t den angivna lokalen oförändrad och utelämnar den om den saknas eller är undefined; det identifierar inte lokalen automatiskt. Servern validerar värdet och normaliserar det till en stödd baskod. Felaktigt formaterade eller språk som inte stöds ger HTTP 400 Invalid uiLocale i stället för att tyst falla tillbaka. Locale är presentationskontext som anroparen anger, inte en kontroll för autentisering eller behörighet. SDK:t skickar inte sidkontext (sourceUrl eller sourcePath) eller modellalternativ. Validera att meddelandet inte är tomt och är högst 2 000 tecken efter trimning innan det skickas; backendens interna valideringsfel visas för närvarande som generiska HTTP 500-fel.

SDK:t skickar den offentliga API-nyckeln i JSON-kroppen.

Med aktuell källkod och backend kan du till exempel anropa chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }).

En identifierad språksignal i frågan har företräde framför uiLocale för produktens egna reservmeddelanden. Om språket inte kan identifieras, eller om identifieringen enbart bygger på den ASCII-baserade engelska heuristiken, kan UI-lokalen avgöra språket. Om ingetdera finns används produktens standardvärden. Ett reservmeddelande som projektet har skrivit används ordagrant i stället för produktens reservmeddelande utan kontext. UI-lokalen översätter inte projektets reservtext och ändrar inte AI-genererat innehåll.

Widget-/chat-API:t i aktuell källkod lägger till productFallback endast för produktens egna svar utan kontext. Om fältet är tillgängligt beror på backendversionen, inte SDK-versionen. no_context_ui betyder att reservtextens språk valdes utifrån UI- eller standardspråket, eller att det inte kunde fastställas; ett eget gränssnitt kan lokalisera om texten med den aktuella katalogposten message.noContext. no_context_question betyder att den befintliga klassificeraren kände igen frågans språk; behåll den returnerade meddelandetexten. Markören garanterar inte att språket identifierades korrekt. Markören saknas för projektspecifika reservtexter, vanliga svar, leverantörsfel och svar från äldre backendversioner. Dra inte slutsatser om textens ursprung utifrån att meddelandetexten överensstämmer med någon annan text eller att markören saknas, och ignorera okända framtida markörvärden.

Det publicerade SDK:t 0.1.4 deklarerar inte productFallback i ChatResponse, men vidarebefordrar fältet i det returnerade JSON-objektet om backend skickar det. Typkontrollera värdet säkert innan du använder det. Det finns inget allmänt wasAnswered-fält eller statusfält för reservsvar, så hitta inte på ett strukturerat resultat för frågor som inte kan besvaras. En identisk slutförd begäran kan spelas upp igen med samma idempotencyKey; då returneras den ursprungliga svarstexten och markören, om en sådan fanns, oförändrade utan att begäran körs igen.

Headless sendMessage() försöker inte automatiskt igen. Om du implementerar återförsök ska du använda en unik idempotencyKey per logiskt meddelande och samma nyckel och exakt samma indata för varje återförsök. Bevara den ursprungliga uiLocale-inställningen, även om den utelämnades: den aktuella servern inkluderar den normaliserade lokalen i begärans idempotensfingeravtryck. Skapa inte en ny nyckel efter ett oklart transportfel och försök inte blint igen vid varje 409.

sendMessage() erbjuder inte strömning, tidsgränser, ett AbortSignal-alternativ, lagring eller UI-tillstånd. En anpassad fetch kan tillhandahålla transportpolicy. Avsaknaden av automatiska återförsök gäller headless-chatt: SDK 0.1.4 försöker enbart getWidgetConfig() igen en gång efter HTTP 400 och den hostade v15-loadern försöker sina GET-förfrågningar vid start igen.

Fortsätt en konversation​

Spara det returnerade konversations-ID:t i gränssnittets tillstånd och skicka med det i nästa meddelande:

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

Återanvänd inte ett konversations-ID för obesläktade besökare. Skapa en ny konversation genom att utelämna conversationId i deras första meddelande. ID:t grupperar lagrade meddelanden; med samma conversationId får modellen upp till 12 nyligen sparade meddelanden, vart och ett begränsat till 2 000 tecken. Det är begränsad kontext, inte hela transkriptet eller permanent minne; upprepa äldre detaljer vid behov.

Även null startar en ny konversation.

Säkerhet vid återförsök​

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.

Ange en unik idempotencyKey per logiskt meddelande och behåll exakt samma indata, inklusive ursprungligt conversationId, vid återförsök. SDK:t skickar nyckeln som Idempotency-Key men skapar den inte och försöker inte igen åt dig. Nycklar gäller per projekt och ska bestå av 1–128 tecken enligt [A-Za-z0-9][A-Za-z0-9._:-]*. Ändrade indata, en pågående förfrågan eller ett terminalt fel kan ge 409.

Återspelning är inte permanent: slutförda och misslyckade poster upphör 24 timmar efter reservationen, medan pågående poster inte återtas enbart för att tiden gått. Ett återförsök efter att en terminal post löpt ut kan köras igen. Begränsa återförsöksfönstret och undersök ihållande konflikter i stället för att anta obegränsad deduplicering.

Hantera fel​

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);
} else {
// Nätverksfel och andra fel som inte är HTTP-fel omsluts inte av SDK:t.
console.error(error);
}
}

ChattyboxError.status innehåller HTTP-statusen. code finns när API:t returnerar en sträng som felkod. Felaktigt formaterad eller ostödd uiLocale ger HTTP 400 i den aktuella backendkällkoden.

Svar utanför 2xx, en icke-tom error-sträng även vid HTTP 200, ogiltig JSON och JSON som inte är ett objekt ger ChattyboxError. Nätverks- och fetchfel skickas vidare oförändrade. SDK 0.1.4 omsluter även oläsbara svarskroppar med koden RESPONSE_BODY_READ_FAILED. Lyckade JSON-objekt typas utan fältvis validering vid körning.

Vanliga HTTP-statusar är 400 för felaktiga indata eller språk som inte stöds, 401 för nyckel- eller originfel, 403 för en inaktiverad projektwidget även vid headless-chatt, 409 för idempotenskonflikter, 413 för chattförfrågningar över 65 536 byte, 429 för hastighetsbegränsning och 500 för interna fel. SDK:t exponerar inte svarsheaders i resultatet eller felet.

Återanvänd projektinställningar och översättningar​

SDK:t tillhandahåller också getWidgetConfig() och getWidgetTranslations(locale). Metoderna stöder klienter som vill återskapa den hostade widgetens projektinställningar och lokaliserade etiketter:

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

Ett helt anpassat gränssnitt kan ignorera dem. Spara varje besökares conversationId i besökarens webbläsare eller sessionstillstånd; dela aldrig ett globalt konversations-ID.

getWidgetConfig() autentiserar med Authorization: Bearer. SDK 0.1.4 försöker exakt en gång till med en kodad nyckel i querysträngen endast efter HTTP 400, för mellanliggande system som tar bort headern; andra statusar ger inga återförsök. WidgetConfig är Record<string, unknown> med valfria typade inställningar för bland annat aktivering, färger, position, texter, varumärke och språk. Typavgränsa ytterligare okända fält innan de används. En lyckad konfigurationsförfrågan markerar också projektet som widgetinstallerat, även om din klient inte visar en widget.

I typerna i den aktuella SDK-källkoden har WidgetConfig de valfria fälten headerTitleIsDefault?: boolean och welcomeMessageIsDefault?: boolean. Varje flagga beskriver motsvarande text: true betyder produktens lokaliserade standardtext, medan false betyder en anpassad sträng som ska bevaras. Om en flagga saknas, även i äldre svar, är textens ursprung okänt; jämför aldrig texten med en standardtext för att dra slutsatser om dess ursprung. Tillgängligheten beror på backendversionen, inte SDK-versionen. Det publicerade SDK:t 0.1.4 deklarerar inte dessa flaggor som booleska värden, men typen Record<string, unknown> och det oförändrade JSON-svaret gör att konsumenter säkert kan typavgränsa dem när de finns. Lyckade svar valideras eller typomvandlas inte fält för fält.

getWidgetTranslations(locale) returnerar Promise<WidgetTranslations> med translations: Record<string, string>, dir: 'ltr' | 'rtl' och serverns valda locale: string. Slutpunkten är offentlig och använder inte API-nyckeln eller projektets språkinställningar. Ange en av en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy eller cs. SDK:t URL-kodar men normaliserar inte språkkoden: fr-CA och FR ger 400, till skillnad från den hostade widgetens normalisering. En tom sträng väljer engelska på servern. Alla aktuella kataloger är LTR och kan cachelagras i en timme.

För ett eget gränssnitt väljer du själv språk, respekterar allowLocaleOverride och projektets fasta eller automatiska läge om du vill återskapa den hostade widgetens beteende, och tillhandahåller reservvärden för saknade översättningsnycklar. Inställningarna styr gränssnittets etiketter; en headless-klient i aktuell källkod kan separat ange uiLocale för produktens egna reservmeddelanden enligt beskrivningen ovan. Varken inställningarna eller uiLocale garanterar svarskvalitet eller språk i AI-genererade svar.

Nästa steg​