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 sovelluskoodista. Määritä sen julkinen avain ja API-URL ja lataa ylläpidetty kelluva widget pysyvästä selainsovelluksen shellistä tai käytä headless-metodeja omien komponenttiesi kanssa. Täysi widgetin purkaminen edellyttää myös päivitettyä widget.js-tiedostoa; itse hostatuissa asennuksissa se on päivitettävä erikseen.
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, ei komponenttisi sisään; { locale: 'fr' } asettaa alustuksessa pyydetyn kielen, jos projekti sallii script-overriden.
Esimerkkien import.meta.env.PUBLIC_*-nimet ovat havainnollistavia. Käytä frameworkisi julkisen konfiguraation käytäntöä, esimerkiksi Viten import.meta.env.VITE_*- tai Next.js:n process.env.NEXT_PUBLIC_*-muotoa. Node.js:ssä lue ja validoi sen sijaan process.env-arvot.
Hanki julkinen määritys
- Luo projekti ja indeksoi sisältösi.
- Testaa edustavia kysymyksiä kohdassa Testaa chatbottia.
- Tarkista tai luo julkinen selainavain kohdassa Asenna → Avaimet ja verkkotunnukset ja tarkista sen origin-asetukset. Rajoittamattomat avaimet toimivat eri origineissa; verkkosivustolle valmisteltu avain voi jo olla rajoitettu.
- Syötä HTTP(S)-verkkosivusto-URL kohdassa Asenna → Verkkosivuston asennus, valitse sopiva avain ja kopioi koodinpätkän widgetin API-URL. Valitsin näyttää vanhentumattomat avaimet, joilla ei ole rajoituksia tai jotka ovat sallittuja URL:n originille. Valitse rajoitettu avain syöttämällä sallittu origin ja tarkista rajoitukset kohdasta Hallinnoi avaimia ja sallittuja verkkotunnuksia. Jos lomake ei ole käytettävissä, suorita ensin hallintapaneelissa näytetty asennusvaihe.
Julkiset widgetin API-avaimet on tarkoitettu näkymään selainkoodissa. Ne tunnistavat projektin, mutta eivät ole hallintatunnuksia. Kohdassa Asenna → Avaimet ja verkkotunnukset → Muokkaa origin-osoitteita voit ottaa käyttöön valinnaisen origin-rajoituksen lisäsuojaksi. Se täsmää tarkasti normalisoituun skeemaan, isäntään ja porttiin, ei polkuihin tai jokerimerkillä määritettyihin aliverkkotunnuksiin. Rajoitettu avain tarkistaa pyynnön Origin-otsakkeen tai Referer-otsakkeen originin; puuttuva tai kielletty origin palauttaa 401 Invalid API key, kuten virheellinen tai vanhentunut avainkin. Node.js:n fetch ei lähetä näitä selaimen otsakkeita automaattisesti. Origin-tarkistus ei ole autentikointia eikä estä muita kuin selainasiakkaita väärentämästä otsakkeita. Paketti on ESM-asiakas nykyaikaisille Node.js- ja selainohjelmille, jotka tarjoavat fetch-funktion.
Konstruktori ja viennit
new Chattybox(options) vaatii epätyhjät apiKey- ja baseUrl-merkkijonot. SDK 0.1.4 vaatii baseUrl-arvoksi absoluuttisen HTTP(S)-URL-osoitteen ilman tunnistetietoja, kyselymerkkijonoa tai fragmenttia. Valinnainen fetch on fetch-yhteensopiva funktio; muuten käytetään globaalia fetch-funktiota. Kopioi widget-API:n HTTP-URL asennuskoodista, älä hallintapaneelin tai Convexin .cloud-asiakasosoitetta. Lopun vinoviivat ja sen jälkeen lopussa oleva /chat poistetaan. Asiakas tarjoaa vain luettavat apiKey- ja normalisoidun baseUrl-ominaisuuden. Virheelliset asetukset aiheuttavat tavallisen Error-virheen.
Paketti vie Chattybox- ja ChattyboxError-luokat sekä tyypit ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions ja HostedWidgetHandle. Se ei sisällä React-komponenttia tai hookeja. ./browser-IIFE-paketti tarjoaa luokat window.ChattyboxSDK-oliossa, mutta pelkkä sen lataaminen ei liitä käyttöliittymää.
Liitä hostattu widget koodista
Käytä tätä, kun haluat alustaa ChattyBoxin ylläpidetyn kelluvan käyttöliittymän 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 synkronisesti ennen kuin skripti on latautunut tai käyttöliittymä valmis. Kahvan element on lisätty tai uudelleenkäytetty HTMLScriptElement. scriptUrl on oletuksena https://chattybox.ai/widget.js; muuta sitä vain luotettua esikatselu- tai itse hostattua lataajaa varten. locale asettaa data-locale-arvon, jos se ei ole tyhjä ja projekti sallii ohituksen; debug ottaa diagnostiikan käyttöön, kun sen arvo on totuudellinen.
Julkaistussa SDK:ssa 0.1.4 identtiset mountit jakavat skriptin ja jokaisella kahvalla on viite. Poista kaikki kahvat: remove() on idempotentti ja viimeinen kahva signaloi poiston. Hostatun widget.js v15:n kanssa se keskeyttää alustuksen, uudelleenyritykset ja käynnissä olevan chatin sekä poistaa widgetin omat käyttöliittymäelementit, tyylit, fonttilinkit, skriptin ja globaalin API:n. window.ChattyBox.destroy() on hostatun v15:n vastaava toiminto. Purkaminen ei voi perua palvelimen jo käsittelemää pyyntöä. Eri avain, API-URL, scriptUrl, locale tai debug-valinta hylätään, kunnes kaikki aiemmat kahvat on poistettu.
SDK ei tunnista merkitsemättömiä manuaalisia lataajia. Valitse vain yksi integraatiotapa sivua kohden; älä yhdistä SDK-mountia lisäosaan, GTM-tagiin tai erilliseen skriptiin. Konstruktorin mukautettua fetch-funktiota käyttävät vain headless-metodit, ei hostattu widget. SDK:ssa ei ole valmiuslupausta, säiliökohdetta eikä reaktiivista locale-API:a. Nykyisen lähdekoodin loader seuraa skriptin data-locale-attribuutin muutoksia; tämä on loaderin toimintaa, ei SDK-rajapinta. Tarkista käytössä olevan loaderin versio.
Hostattu v15-loader yrittää siirtovirheitä, keskeytyneitä onnistuneita vastausrunkoja, käsittelyssä olevia vastauksia, nopeusrajoituksia ja palvelinvirheitä uudelleen samalla pyynnöllä ja idempotenssiavaimella. Yrityksiä on yhteensä enintään 10 eikä uutta automaattista yritystä ajoiteta yli 30 sekunnin päähän; luettavat Retry-After-viiveet lasketaan mukaan. Yritysten loputtua Yritä lähettää viesti uudelleen käyttää samaa loogista pyyntöä; uusi kysymys aloittaa uuden pyynnön. Virheellinen JSON tai vastausrakenne onnistuneessa vastauksessa on lopullinen protokollavirhe, ei automaattisen uudelleenyrityksen aihe. Eri originista tulevan API-vastauksen on paljastettava Retry-After otsakkeella Access-Control-Expose-Headers.
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 kohdassa Verkkosivuston asennus 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 tai määritetty varavastaus; näytä turvallisesti tekstinä tai puhdistettuna Markdownina, ei raakana HTML:nä. |
conversationId | string | Tämän keskustelun jatkamiseen käytettävä tunniste. |
sources | string[] | Vastaukseen haettujen lähteiden URL-osoitteet; varavastauksella ne voivat olla tyhjät. Validoi HTTP(S)-osoitteet ennen linkkien näyttämistä. |
productFallback | 'no_context_ui' | 'no_context_question' (valinnainen, nykyinen lähdekoodi) | Tunnistaa tuotteen oman kontekstittoman varavastauksen ja kertoo, miten sen kieli valittiin; katso alta. |
providerError | string (valinnainen, nykyinen lähdekoodi) | Rakenteinen virhekoodi mallipalvelun virheestä. Kenttä puuttuu tavallisista vastauksista ja määritetyistä varavastauksista. Käsittele tuntemattomia koodeja yleisenä virheenä. |
sendMessage(input) palauttaa Promise<ChatResponse>-arvon. SendMessageInput hyväksyy message: string-, valinnaisen conversationId: string | null- ja valinnaisen idempotencyKey: string-arvon. Nykyinen lähdekoodi hyväksyy myös valinnaisen uiLocale: string-arvon; sitä ei ole julkaistussa SDK-versiossa 0.1.4. Nykyisen lähdekoodin SDK välittää annetun lokaalin muuttamattomana ja jättää sen pois, jos se puuttuu tai on undefined; se ei tunnista lokaalia automaattisesti. Palvelin validoi arvon ja normalisoi sen tuetuksi peruskieleksi. Virheellinen tai tukematon arvo palauttaa HTTP 400 -virheen Invalid uiLocale sen sijaan, että palvelin siirtyisi hiljaisesti varavaihtoehtoon. Locale on kutsujan antamaa esityskontekstia, ei todennus- tai käyttöoikeusmekanismi. SDK lähettää julkisen API-avaimen JSON-rungossa, mutta ei sivukontekstia (sourceUrl tai sourcePath) eikä malliasetuksia. Varmista ennen lähettämistä, että viesti ei ole tyhjä ja on trimmaamisen jälkeen enintään 2 000 merkkiä; taustajärjestelmän sisäiset validointivirheet palautuvat tällä hetkellä yleisinä HTTP 500 -virheinä.
Nykyisen lähdekoodin SDK:lla ja backendillä voit esimerkiksi kutsua chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }).
Tunnistettu signaali kysymyksen kielestä ohittaa uiLocale-arvon tuotteen omissa varavastauksissa. Jos kieltä ei pystytä päättelemään tai tunnistus perustuu vain ASCII-merkkeihin nojaavaan englannin heuristiikkaan, UI-lokaali voi määrittää niiden kielen. Jos kumpaakaan ei ole, käytetään tuotteen oletusarvoja. Projektin kirjoittama varavastaus näytetään sellaisenaan tuotteen kontekstittoman varavastauksen sijaan. UI-lokaali ei käännä projektin omaa varavastaustekstiä eikä muuta tekoälyn luomaa sisältöä.
Nykyisen lähdekoodin widget/chat-API lisää productFallback-kentän vain tuotteen omiin kontekstittomiin varavastauksiin. Kentän saatavuus riippuu backend-versiosta, ei SDK-versiosta. no_context_ui tarkoittaa, että varavastauksen kieli valittiin UI-lokaalin tai oletuslokaalin perusteella tai sitä ei pystytty määrittämään; oma käyttöliittymä voi lokalisoida tekstin uudelleen käyttämällä nykyisen käännöskatalogin message.noContext-merkintää. no_context_question tarkoittaa, että nykyinen luokitin tunnisti kysymyksen kielen; säilytä palautettu viestiteksti sellaisenaan. Merkintä ei takaa, että kieli tunnistettiin oikein. Merkintä puuttuu projektin omista varavastauksista, tavallisista vastauksista, mallipalvelun virheistä ja vanhoista backend-vastauksista. Älä päättele viestin alkuperää viestitekstin yhtäläisyyden tai merkinnän puuttumisen perusteella, ja ohita tuntemattomat tulevat merkintäarvot.
Julkaistu SDK 0.1.4 ei määrittele productFallback-kenttää ChatResponse-tyypissä, mutta välittää kentän palautetussa JSON-objektissa, jos backend toimittaa sen. Tarkista arvon tyyppi turvallisesti ennen käyttöä. Yleistä wasAnswered- tai varavastauksen tilakenttää ei ole, joten älä keksi rakenteista tulosta sille, ettei kysymykseen ole vastausta. Saman valmiiksi käsitellyn pyynnön voi toistaa samalla idempotencyKey-arvolla; tällöin alkuperäinen vastaus ja mahdollinen merkintä palautetaan täsmälleen ennallaan ilman pyynnön uutta suorittamista.
Headless-sendMessage() ei tarjoa suoratoistoa, automaattisia uudelleenyrityksiä, aikakatkaisuja, AbortSignal-valintaa, tallennusta tai käyttöliittymän tilaa. Mukautettu fetch voi toteuttaa siirtokäytännön. SDK 0.1.4 yrittää erikseen getWidgetConfig()-pyynnön kerran uudelleen HTTP 400:n jälkeen; hostatun loaderin aloitushaut ovat eri toiminto.
Jos toteutat uudelleenyrityksiä, käytä yksilöllistä idempotencyKey-arvoa kutakin loogista viestiä kohti ja säilytä sama avain ja täsmälleen samat syötetiedot, myös alkuperäinen conversationId, yritysten välillä. SDK ei luo avainta. Avain on projektikohtainen, 1–128 merkkiä ja vastaa muotoa [A-Za-z0-9][A-Za-z0-9._:-]*. Säilytä alkuperäinen uiLocale-asetus, myös silloin kun se jätettiin pois: nykyinen palvelin sisällyttää normalisoidun lokaalin pyynnön idempotenssisormenjälkeen. Muuttunut syöte, keskeneräinen pyyntö tai lopullinen virhe voi palauttaa 409. Älä luo uutta avainta epäselvän siirtovirheen jälkeen äläkä yritä sokkona uudelleen jokaisen 409-virheen yhteydessä. Valmiit ja epäonnistuneet tietueet vanhenevat 24 tunnin kuluttua varauksesta, mutta odottavia tietueita ei vapauteta pelkän ajan perusteella; vanhenemisen jälkeen uusi yritys voi suorittua uudelleen.
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.
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; myös null aloittaa uuden keskustelun. 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 vain, kun API palauttaa koodin merkkijonona; useimmat nykyiset widget-API:n virheet eivät sisällä sitä. Ei-2xx-vastaukset, epätyhjä merkkijonomuotoinen error myös HTTP 200 -vastauksessa, virheellinen JSON ja JSON, joka ei ole objekti, aiheuttavat ChattyboxError-virheen. Verkko- ja fetch-virheitä ei kääritä siihen. SDK 0.1.4 käärii myös lukukelvottoman vastausrungon RESPONSE_BODY_READ_FAILED-koodilla. Onnistuneen JSON-objektin kenttiä ei validoida ajonaikaisesti yksitellen.
Mahdollisia HTTP-tiloja ovat 400 virheelliselle syötteelle tai tukemattomalle käännöslokaalille, 401 avain- tai origin-virheelle, 403 käytöstä poistetulle widgetille myös headless-chatissa, 409 idempotenssiristiriidalle, 413 yli 65 536 tavun chat-rungolle, 429 nopeusrajoitukselle ja 500 sisäiselle virheelle. SDK ei paljasta vastausotsakkeita tuloksessa tai virheessä.
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 message-, valinnaisen conversationId- ja valinnaisen idempotencyKey-arvon. Nykyinen lähdekoodi hyväksyy lisäksi valinnaisen uiLocale-arvon; sitä ei ole julkaistussa SDK-versiossa 0.1.4. Metodi ei lähetä sivukontekstia (sourceUrl tai sourcePath) eikä malliasetuksia. Vahvista ennen lähetystä enintään 2 000 merkin ei-tyhjä viesti ja käytä yhtä yksilöllistä idempotenssiavainta loogista viestiä kohden.
getWidgetConfig() palauttaa Promise<WidgetConfig>-arvon ja käyttää Authorization: Bearer -otsaketta. SDK 0.1.4 yrittää vain HTTP 400:n jälkeen kerran uudelleen URL-koodatulla kyselyparametrin avaimella; muita tiloja se ei yritä uudelleen. WidgetConfig on Record<string, unknown>, jossa on valinnaisia tyypitettyjä widgetin ulkoasuun, käyttöön ja kieliasetuksiin liittyviä ominaisuuksia. Tarkista muiden kenttien tyypit ennen käyttöä. Onnistunut konfiguraatiopyyntö merkitsee projektin widgetin asennetuksi, vaikka oma asiakas ei näyttäisi widgetiä. Katso oletusarvot kohdasta Hostatun widgetin mukauttaminen.
getWidgetTranslations(locale) palauttaa Promise<WidgetTranslations>-arvon, jossa on translations: Record<string, string>, dir: 'ltr' | 'rtl' ja palvelimen valitsema locale. Julkinen päätepiste ei käytä API-avainta tai projektin kieliasetuksia. Tuetut koodit ovat en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy ja cs. SDK URL-koodaa arvon muttei normalisoi sitä: fr-CA ja FR palauttavat 400, kun taas tyhjä merkkijono valitsee palvelimella englannin. Nykyiset luettelot ovat vasemmalta oikealle ja niitä voi säilyttää välimuistissa tunnin. Omassa käyttöliittymässä ratkaise locale itse, huomioi projektin asetukset, jos toisinnat hostatun toiminnan, ja varaudu puuttuviin käännösavaimiin. Kieliasetukset eivät takaa tekoälyvastausten laatua tai kieltä.
Nykyisen SDK-lähdekoodin tyypeissä WidgetConfig-tyypillä on valinnaiset kentät headerTitleIsDefault?: boolean ja welcomeMessageIsDefault?: boolean. Kumpikin lippu kuvaa vastaavaa tekstikenttää: true tarkoittaa tuotteen lokalisoitua oletustekstiä, kun taas false tarkoittaa mukautettua merkkijonoa, joka on säilytettävä. Jos lippu puuttuu, myös vanhemmista vastauksista, tekstin alkuperä on tuntematon; älä koskaan päättele alkuperää vertaamalla tekstiä oletustekstiin. Kenttien saatavuus riippuu backend-versiosta, ei SDK-versiosta. Julkaistun SDK-version 0.1.4 tyypit eivät määrittele näitä lippuja boolean-tyyppisiksi, mutta Record<string, unknown>-tyyppi ja muuttumaton JSON-vastaus mahdollistavat niiden turvallisen tyypin tarkistamisen silloin, kun ne toimitetaan. Onnistuneita vastauksia ei validoida eikä pakoteta tyyppeihin kenttä kerrallaan.
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 varavastaukset, lähdeviitteet ja mobiilikäyttäytyminen julkaisun tarkistuslistan avulla. Testaa myös tarkat origin-osoitteet, jos otat origin-rajoituksen käyttöön.