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. Importera en klient i applikationen, konfigurera dess offentliga nyckel och API-URL och montera sedan det underhållna gränssnittet där applikationen behöver det, eller använd headless-metoderna med egna komponenter.

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.

Hämta din offentliga konfiguration

1. Skapa ett projekt och indexera ditt innehåll.
2. Testa representativa frågor i instrumentpanelen.
3. Öppna Public Keys och skapa en webbläsarnyckel. Den fungerar från produktion, preview, staging och localhost som standard.
4. Öppna Embed, välj nyckeln och kopiera widgetens API-URL som visas tillsammans med det genererade kodfragmentet.

Offentliga API-nycklar för widgeten är avsedda att visas i webbläsarkod. De identifierar ett projekt men är inte administrativa autentiseringsuppgifter. Originbegränsning är valfri defense-in-depth och matchar exakt schema, värd och port; den är inte autentisering. Paketet är en ESM-klient för moderna Node.js- och webbläsarapplikationer som tillhandahåller fetch.

Montera den hostade widgeten från kod

Använd detta när du vill ha ChattyBox underhållna gränssnitt men styra var det monteras 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() återger ett handtag innan scriptet eller UI:t är redo. I det publicerade SDK:t 0.1.4 delar identiska mountar scriptet och varje handtag äger en referens: remove() är idempotent och först det sista handtaget avbryter initiering, återförsök och pågående chatt och tar sedan bort UI, stilar, fontlänkar, script och global API. En annan nyckel, API-URL, scriptUrl, locale eller debug-option avvisas så länge handtag finns kvar. Med widget.js v15 utför window.ChattyBox.destroy() samma teardown. Det finns ingen ready-promise, container eller reaktiv språkändring.

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 på fliken Embed. SDK:t accepterar både distributionsroten och en URL som slutar på /chat.

Svaret innehåller:

Fält	Typ	Beskrivning
message	string	Svarstext eller konfigurerat reservsvar; rendera säkert.
conversationId	string	Identifierare som används för att fortsätta denna konversation.
sources	string[]	Käll-URL:er; kan vara tom för reservsvar.

sendMessage() accepterar endast message, valfri conversationId och valfri idempotencyKey. Den skickar inte sourceUrl, sourcePath, locale eller modelloptioner. Validera icke-tomma, högst 2 000 tecken långa meddelanden och återanvänd samma idempotensnyckel med exakt samma indata vid en osäker retry. SDK:t gör inga automatiska retries; skapa inte en ny nyckel eller retrya blint vid varje 409.

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, men tidigare turer skickas för närvarande inte till modellen: gör följdfrågor självbärande.

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

ChattyboxError.status innehåller HTTP-statusen. code finns när API:t returnerar en strukturerad felkod.

Å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.

Nästa steg

• Föredrar du ett underhållet gränssnitt utan byggsteg? Installera widget.js.
• Anpassa det hostade gränssnittet i Anpassning av den hostade widgeten.
• Testa originbegränsningar, reservsvar, källhänvisningar och mobilbeteende med lanseringschecklistan före lansering.