JavaScript SDK

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

// Call this from your component's cleanup lifecycle when appropriate.
// widget.remove();

Anropa mountWidget() i webbläsarkod från den komponent eller layout där det underhållna gränssnittet ska vara tillgängligt. Du kan skicka { locale: 'fr' } för en lokal för en specifik rutt.

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, skapa en webbläsarnyckel och begränsa dess tillåtna origins.
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. Begränsa webbläsarnycklar till de domäner som ska få anropa din chattbot. 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();

// Optional cleanup for a component lifecycle:
widget.remove();

Det laddar det underhållna gränssnittet en gång och är inte tillgängligt under serverrendering.

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	Det genererade svaret.
conversationId	string	Identifierare som används för att fortsätta denna konversation.
sources	string[]	Käll-URL:er som hämtats för svaret.

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.

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.