JavaScript SDK

npm-paketti on suositeltu tapa integroida ChattyBox. Tuo yksi asiakas sovellukseesi, määritä sen julkinen avain ja API-URL ja liitä ylläpidetty käyttöliittymä siihen, missä sovelluksesi tarvitsee sitä, tai käytä headless-metodeja omien komponenttiesi kanssa.

Pika-aloitus

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

Kutsu mountWidget() selainkoodissa siitä komponentista tai layoutista, jossa ylläpidetyn käyttöliittymän tulee olla käytettävissä. Voit välittää { locale: 'fr' } reittikohtaista kielialuetta varten.

Hanki julkinen määritys

1. Luo projekti ja indeksoi sisältösi.
2. Testaa edustavia kysymyksiä hallintapaneelissa.
3. Avaa Public Keys, luo selainavain ja rajoita sen sallitut origin-osoitteet.
4. Avaa Embed, valitse kyseinen avain ja kopioi luodun koodinpätkän yhteydessä näkyvä widgetin API-URL.

Julkiset widgetin API-avaimet on tarkoitettu näkymään selainkoodissa. Ne tunnistavat projektin, mutta eivät ole hallintatunnuksia. Rajoita selainavaimet verkkotunnuksiin, joiden tulee voida kutsua chatbotiasi. Paketti on ESM-asiakas nykyaikaisille Node.js- ja selainohjelmille, jotka tarjoavat fetch-funktion.

Liitä hostattu widget koodista

Käytä tätä, kun haluat ChattyBoxin ylläpidetyn käyttöliittymän mutta haluat hallita sen liittämispaikkaa sovelluskoodista:

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

Se lataa ylläpidetyn käyttöliittymän kerran, eikä se ole käytettävissä palvelinrenderöinnin aikana.

Rakenna oma käyttöliittymä

Käytä alla olevia headless-metodeja, kun sovelluksesi hallitsee viestiluetteloa, syötettä, lataus- ja virhetiloja, lähdeviitteitä ja saavutettavuutta.

Lähetä viesti

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

Aseta PUBLIC_CHATTYBOX_API_URL täsmälleen Embed-välilehdellä näkyväksi widgetin API-URL:ksi. SDK hyväksyy sekä käyttöönoton juuriosoitteen että /chat-päätteisen URL:n.

Vastaus sisältää:

Kenttä	Tyyppi	Kuvaus
message	string	Luotu vastaus.
conversationId	string	Tämän keskustelun jatkamiseen käytettävä tunniste.
sources	string[]	Vastaukseen haettujen lähteiden URL-osoitteet.

Jatka keskustelua

Pidä palautettu keskustelun tunniste käyttöliittymäsi tilassa ja lähetä se seuraavan viestin mukana:

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

Älä käytä samaa keskustelun tunnistetta toisiinsa liittymättömillä kävijöillä. Luo uusi keskustelu jättämällä conversationId pois heidän ensimmäisestä viestistään.

Käsittele virheet

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 sisältää HTTP-tilakoodin. code on mukana, kun API palauttaa rakenteisen virhekoodin.

Käytä projektin asetuksia ja käännöksiä uudelleen

SDK tarjoaa myös metodit getWidgetConfig() ja getWidgetTranslations(locale). Niiden avulla asiakkaat voivat toisintaa hostatun widgetin projektiasetukset ja lokalisoidut tunnisteet:

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

Täysin mukautettu käyttöliittymä voi jättää ne huomiotta. Säilytä kunkin kävijän conversationId hänen selaimensa tai istuntonsa tilassa; älä koskaan jaa yhtä yleistä keskustelun tunnistetta.

Seuraavat vaiheet

• Haluatko mieluummin ylläpidetyn käyttöliittymän ilman build-vaihetta? Asenna widget.js.
• Mukauta hostattua käyttöliittymää kohdassa Hostatun widgetin mukauttaminen.
• Testaa ennen julkaisua origin-rajoitukset, varavastaukset, lähdeviitteet ja mobiilikäyttäytyminen julkaisun tarkistuslistan avulla.