Siirry pääsisältöön
ChattyBox Logo

JavaScript SDK

:::note Versiotila Julkaistu npm-SDK 0.1.4 validoi baseUrl-arvon, kapseloi lukukelvottomat vastausrungot ja yrittää config-HTTP-400:n uudelleen vain kerran. widget.js v15:n kanssa remove()/window.ChattyBox.destroy() tukee teardownia; headless-sendMessage() ei yritä automaattisesti uudelleen. :::

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

chattybox.mountWidget();

// Pidä loader sivun elinkaaren ajan myös SPA-navigoinnissa.

Kutsu mountWidget() vasta kun document.body on olemassa, ei renderöinnin tai palvelinsuorituksen aikana. Se lisää kelluvan widgetin document.body-alle; { locale: 'fr' } pyytää kieltä vain alustuksessa, jos projekti sallii script-overriden.

Hanki julkinen määritys​

  1. Luo projekti ja indeksoi sisältösi.
  2. Testaa edustavia kysymyksiä hallintapaneelissa.
  3. Avaa Public Keys ja luo selainavain. Se toimii oletuksena production-, preview-, staging- ja localhost-origineista.
  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. Origin-rajoitus on vapaaehtoinen lisäsuoja ja täsmää tarkasti schemeen, hostiin ja porttiin; se ei ole autentikointia. Rajoitettu avain tarkistaa pyynnön Origin-otsakkeen tai Referer-otsakkeen originin, joten Node.js:n fetch ei lähetä näitä selaimen otsakkeita automaattisesti. 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,
});

chattybox.mountWidget({ locale: 'fr', debug: false });

mountWidget() palauttaa kahvan ennen kuin script tai UI on valmis. Julkaistussa SDK:ssa 0.1.4 identtiset mountit jakavat scriptin ja jokaisella kahvalla on viite: remove() on idempotentti ja vasta viimeinen kahva keskeyttää alustuksen, uudelleenyritykset ja käynnissä olevan chatin sekä poistaa sitten UI:n, tyylit, fonttilinkit, scriptin ja globaalin API:n. Eri avain, API-URL, scriptUrl, locale tai debug-valinta hylätään niin kauan kuin kahvoja on. widget.js v15:n kanssa window.ChattyBox.destroy() tekee saman teardownin. Ready-promisea, konttikohdetta tai reaktiivista locale-päivitystä ei ole.

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äTyyppiKuvaus
messagestringLuotu vastaus tai määritetty varavastaus.
conversationIdstringTämän keskustelun jatkamiseen käytettävä tunniste.
sourcesstring[]Vastaukseen haettujen lähteiden URL-osoitteet; varavastauksella ne voivat olla tyhjät.

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. Tunniste ryhmittelee tallennetut viestit; samalla conversationId-arvolla malli saa enintään 12 viimeisintä tallennettua viestiä, kukin katkaistuna 2 000 merkkiin. Tämä on rajattua kontekstia, ei koko keskustelun teksti eikä pysyvä muisti; toista vanhemmat yksityiskohdat tarvittaessa.

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. sendMessage() hyväksyy vain message-, conversationId- ja idempotencyKey-arvot: se ei lähetä sivukontekstia (sourceUrl tai sourcePath), localea eikä malliasetuksia. Vahvista ennen lähetystä enintään 2 000 merkin ei-tyhjä viesti ja käytä yhtä yksilöllistä idempotenssiavainta loogista viestiä kohden.

Seuraavat vaiheet​