JavaScript SDK
:::note Versiooni olek
Avaldatud npm-SDK 0.1.4 valideerib baseUrl-i, mähendab loetamatud vastuse kehad ja proovib config HTTP 400 ainult ühe korra uuesti. Koos widget.js v15-ga toetavad remove()/window.ChattyBox.destroy() teardowni; headless sendMessage() ei korda automaatselt. Avaldatud SDK 0.1.4 ei toeta uiLocale-i; allpool kirjeldatud uiLocale-käitumine kehtib praeguse lähtekoodi SDK ja backendi kohta.
:::
npm-pakett on soovitatav viis ChattyBoxi integreerimiseks rakendusekoodist. Seadistage selle avalik võti ja API URL ning laadige hallatav ujuv vidin brauseri püsivast paigutusest või kasutage peata meetodeid oma komponentidega. Täielik vidina eemaldamine nõuab ka uuendatud hostitud widget.js-i; ise hostitud paigalduse korral tuleb seda faili eraldi uuendada.
Kiire alustamine
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();
// Hoia see laadija lehe eluea jooksul alles, ka SPA-navigeerimisel.
Kutsuge mountWidget() välja pärast document.body olemasolu, mitte renderdamise või serveripoolse käituse ajal. See lisab ujuva vidina document.body alla, mitte komponendi sisse. { locale: 'fr' } taotleb vidina algkäivitusel prantsuse keelt, kui projekt lubab skripti lokaadi override’e.
Näidete import.meta.env.PUBLIC_* nimed on illustratiivsed. Kasutage oma raamistiku avaliku konfiguratsiooni tava, näiteks Vite’is import.meta.env.VITE_* või Next.js-is process.env.NEXT_PUBLIC_*. Node.js-is lugege ja valideerige process.env väärtused.
Hankige avalik konfiguratsioon
- Looge projekt ja indekseerige oma sisu.
- Testige tüüpilisi küsimusi vaates Testi vestlusrobotit.
- Jaotises Paigalda → Võtmed ja domeenid kontrollige või looge avalik brauserivõti ning vaadake selle origin’i seadeid. Piiranguteta võtmed töötavad kõigist origin’idest; veebisaidi jaoks ettevalmistatud võti võib juba olla piiratud.
- Jaotises Paigalda → Veebisaidi paigaldamine sisestage veebisaidi HTTP(S) URL, valige sobiv võti ja kopeerige loodud koodilõigu juures olev vidina API URL. Valik näitab aegumata võtmeid, mis on piiranguteta või lubatud selle URL-i origin’i jaoks; piiratud võtme valimiseks sisestage selle lubatud origin. Piiranguid vaadake jaotises Võtmete ja lubatud domeenide haldamine. Kui vorm pole saadaval, lõpetage esmalt juhtpaneelil näidatud seadistussamm.
Avalikud vidina API-võtmed on mõeldud brauserikoodis kasutamiseks. Need tuvastavad projekti, kuid ei ole haldusmandaadid. Valikulise lisakaitse jaoks lubage jaotises Paigalda → Võtmed ja domeenid → Muuda origine piirang ning lisage täpsed brauseri origin’id. Piirang võrdleb normaliseeritud skeemi, hostinime ja porti, mitte teid ega wildcard-alamdomeene. API kasutab päringu Origin-it või selle puudumisel Referer-i origin’it. Piiratud võtme korral annab puuduv või keelatud origin vastuseks 401 Invalid API key, nagu ka vigane või aegunud võti. Node’i fetch ei lisa kumbagi päist automaatselt. Origin’i kontroll ei ole autentimine ega takista brauserivälisel kliendil päiseid võltsida. Pakett on ESM-klient tänapäevastele Node.js-i ja brauserirakendustele, mis pakuvad fetch-i.
Konstruktor ja ekspordid
new Chattybox(options) nõuab mittetühja avalikku vidinavõtit apiKey ja mittetühja baseUrl-i. SDK 0.1.4 puhul peab baseUrl olema absoluutne HTTP(S) URL ilma mandaatide, päringustringi ja fragmendita. Valikuline fetch peab olema fetch-ühilduv funktsioon; muidu kasutatakse globaalset fetch-i. Kopeerige HTTP vidina API URL veebisaidi paigalduskoodist, mitte juhtpaneeli või Convexi .cloud-i URL. Lõpu kaldkriipsud ja seejärel lõpu /chat eemaldatakse. Klient pakub kirjutuskaitstud omadusi apiKey ja normaliseeritud baseUrl.
Konstruktor annab tavalise Error-i, kui valikud puuduvad või pole objekt, võti või URL puudub, pole string või on tühi, antud fetch pole funktsioon või URL ei vasta ülaltoodud nõuetele. Pakett ekspordib Chattybox, ChattyboxError ja tüübid ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions ja HostedWidgetHandle. Reacti komponenti ega hook'e pole. ./browser IIFE-pakett lisab kaks konstruktorit objektile window.ChattyboxSDK, kuid ei laadi kasutajaliidest iseenesest.
Laadige hostitud vidin koodist
Kasutage seda ChattyBoxi hallatava ujuva kasutajaliidese lähtestamiseks rakendusekoodist:
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();
// Kasutage widget.remove() ainult sihipäraseks teardown'iks või nõusoleku tagasivõtuks.
mountWidget() tagastab käepideme sünkroonselt enne skripti või UI valmisolekut. Avaldatud SDK-s 0.1.4 jagavad identsed mountid skripti ja igal käepidemel on viide: remove() on idempotentne ning viimane käepide saadab eemaldamissignaali ja eemaldab skripti. Hostitud widget.js v15 puhul katkestab signaal algkäivituse, korduskatsed ja käimasoleva chati ning eemaldab UI, stiilid, fondilingid ja globaalse API. Erinev võti, API URL, scriptUrl, lokaat või debug-valik lükatakse tagasi, kuni käepidemeid on alles. widget.js v15-ga teeb sama teardowni window.ChattyBox.destroy(). Hoidke loader püsivas shell’is; ärge kombineerige SDK mount’i plugina, GTM-sildi ega eraldi skriptiga. Ready-promise’i, konteineri sihtmärki ega reaktiivset lokaadi-API-t ei ole.
Valikuline scriptUrl on vaikimisi https://chattybox.ai/widget.js; muutke seda ainult usaldusväärse eelvaate või ise hostitud loaderi jaoks. Mittetühi locale määrab data-locale-i, kui projekti allowLocaleOverride seda lubab; tõeväärtusena tõene debug määrab data-debug="true". Käepideme element on lisatud või taaskasutatud HTMLScriptElement. SDK ei tuvasta markerita käsitsi laadijaid ning konstruktori kohandatud fetch-i kasutavad ainult peata meetodid, mitte hostitud vidin. Eemaldamine ei saa tagasi võtta serveris juba töödeldud päringut.
Hostitud v15 loader kordab transporditõrkeid, katkenud edukaid vastusekehi, pooleliolevaid vastuseid, sageduspiiranguid ja serverivigu sama päringukehaga ja idempotentsusvõtmega. Kokku tehakse kuni 10 katset ja automaatset korduskatset ei ajastata pärast 30 sekundi möödumist; loetav Retry-After-i viivitus arvestatakse selle aja sisse. Pärast katsete lõppu kasutab Retry message sama loogilist päringut; uus küsimus alustab uut päringut. Eduka vastuse vigane JSON või vastuse kuju on lõplik protokolliviga. Päise Retry-After lugemiseks peab päritoludevaheline API-vastus selle avaldama päises Access-Control-Expose-Headers.
Looge oma kasutajaliides
Kasutage allolevaid peata meetodeid, kui teie rakendus haldab sõnumiloendit, sisendit, laadimis- ja veaseisundeid, allikaviiteid ning juurdepääsetavust.
Sõnumi saatmine
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);
Seadke PUBLIC_CHATTYBOX_API_URL veebisaidi paigaldamise koodilõigus kuvatud täpseks vidina API URL-iks. SDK aktsepteerib nii juurutuse juur-URL-i kui ka /chat-iga lõppevat URL-i.
Vastus sisaldab järgmist:
| Väli | Tüüp | Kirjeldus |
|---|---|---|
message | string | Vastuse tekst või seadistatud varusõnum; kuvage see turvaliselt teksti või puhastatud Markdownina, mitte toore HTML-ina. |
conversationId | string | Selle vestluse jätkamiseks kasutatav identifikaator. |
sources | string[] | Vastuse allikate URL-id; varuvastuse puhul võib loend olla tühi. Enne linkide kuvamist valideerige HTTP(S) URL-id. |
providerError | string (valikuline, praeguses lähtekoodis) | Struktureeritud teenusepakkuja tõrkekood. Tavaliste vastuste ja seadistatud varuvastuste korral see puudub; tundmatut koodi käsitlege üldise tõrkena. |
productFallback | 'no_context_ui' | 'no_context_question' (valikuline, praeguses lähtekoodis) | Tähistab toote enda konteksti puudumise varuteksti ning seda, kuidas selle keel valiti; vt allpool. |
sendMessage(input) tagastab Promise<ChatResponse>. SendMessageInput aktsepteerib message: string, valikulist conversationId: string | null-i ja valikulist idempotencyKey: string-i. Praeguse lähtekoodi SDK aktsepteerib lisaks valikulist uiLocale: string-i; avaldatud SDK-s 0.1.4 see valik puudub. Praeguse lähtekoodi SDK edastab antud lokaadi muutmata kujul ja jätab selle välja, kui see puudub või on undefined; lokaati automaatselt ei tuvastata. Server valideerib lokaadi ja normaliseerib selle toetatud põhikeeleks. Vigase või toetamata väärtuse korral tagastab server HTTP 400 Invalid uiLocale, mitte ei kasuta vaikselt varukeelt. Näiteks: chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). Lokaal on esituskontekst, mitte autentimis- ega autoriseerimiskontroll.
SDK saadab avaliku API-võtme JSON-päringukehis. Enne saatmist valideerige, et sõnum pole tühi ja selle pikkus pärast äärtest tühimärkide eemaldamist on kuni 2 000 tähemärki. Taustsüsteem jõustab piirangu, kuid selle sisemised valideerimisvead ilmuvad praegu üldise HTTP 500 veana.
Varusõnumite puhul on tuvastatud küsimuse keele signaal uiLocale-ist olulisem. Kui tuvastus pole kindel või põhineb ainult ASCII-tähtedel põhineval inglise keele heuristikal, võib kasutajaliidese lokaal valida toote enda varusõnumite keele. Kui kumbagi signaali pole, rakenduvad toote vaikeseaded. Projekti enda kirjutatud varusõnumit kasutatakse muutmata kujul; uiLocale ei tõlgi seda ega muuda AI loodud vastust ning ei taga vastuse keelt ega kvaliteeti.
Praeguse lähtekoodi vidina-/vestlus-API lisab productFallback-i ainult toote enda konteksti puudumise varusõnumitele; selle välja olemasolu sõltub backendi, mitte SDK versioonist. no_context_ui tähendab, et varusõnumi keel valiti kasutajaliidese või vaikimisi lokaadi põhjal või jäi määramata; kohandatud kasutajaliides võib selle lokaliseerida oma praeguse message.noContext-i kataloogikirje järgi. no_context_question tähendab, et olemasolev klassifikaator tuvastas küsimuse keele; säilitage tagastatud sõnumi tekst. See ei tõenda, et keel tuvastati õigesti. Marker puudub projekti kohandatud varusõnumite, tavaliste vastuste, teenusepakkuja tõrgete ja pärandvastuste korral. Ärge järeldage sõnumi päritolu kunagi teksti võrdlemise ega markeri puudumise põhjal; tundmatuid tulevasi markeri väärtusi eirake.
Avaldatud SDK 0.1.4 ChatResponse-i tüüp ei deklareeri productFallback-i, kuid SDK edastab selle tagastatud JSON-objektis edasi, kui backend selle lisab. Enne kasutamist kitsendage väärtus turvaliselt lubatud väärtuste hulka. Üldist wasAnswered-i ega varuvastuse olekuvälja pole, seega ärge mõelge välja struktureeritud tulemust toetamata vastuse kohta.
Vestluse jätkamine
Hoidke tagastatud vestluse ID-d oma kasutajaliidese olekus ja saatke see järgmise sõnumiga:
const followUp = await chattybox.sendMessage({
message: 'Can you explain the second step?',
conversationId: answer.conversationId,
});
Ärge kasutage sama vestluse ID-d omavahel mitteseotud külastajate puhul. Looge uus vestlus, jättes nende esimese sõnumi juures conversationId välja või määrates selle väärtuseks null. ID rühmitab salvestatud sõnumeid; sama conversationId kasutamisel saab mudel kuni 12 viimast salvestatud sõnumit, igaüks kärbitud 2 000 tähemärgini. See on piiratud kontekst, mitte kogu vestluse tekst ega püsiv mälu; vajaduse korral korrake vanemaid üksikasju.
Vigade käsitlemine
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 sisaldab HTTP olekut. code on olemas ainult siis, kui API tagastab stringi code; enamik praegusi vidina API vigu seda ei tee. Mitte-2xx vastused, mittetühi stringiväli error ka HTTP 200 korral, vigane JSON ja JSON, mis pole objekt, tekitavad ChattyboxError-i. Võrgu- ja fetch-vead edastatakse muutmata kujul. SDK 0.1.4 mähendab ka loetamatu vastusekeha ChattyboxError-iks koodiga RESPONSE_BODY_READ_FAILED. Edukaid JSON-objekte käsitletakse deklareeritud tüübina, välju käitusajal ükshaaval valideerimata.
Levinud HTTP olekud on 400 vigase sisendi või toetamata tõlkelokaadi, 401 võtme või origin’i vea, 403 keelatud projektividina (ka peata vestluse), 409 idempotentsuskonflikti, 413 üle 65 536 baidi vestluspäringukeha, 429 sageduspiirangu ning 500 sisemise vea korral. SDK ei avalda vastuse päiseid tulemuses ega veas.
Projekti seadete ja tõlgete taaskasutamine
SDK pakub ka meetodeid getWidgetConfig() ja getWidgetTranslations(locale). Need toetavad kliente, kes soovivad hostitud vidina projekti seadeid ja lokaliseeritud silte taasesitada:
const [config, labels] = await Promise.all([
chattybox.getWidgetConfig(),
chattybox.getWidgetTranslations('en'),
]);
Praeguse lähtekoodi SDK tüübid määratlevad WidgetConfig-is valikulised väljad headerTitleIsDefault?: boolean ja welcomeMessageIsDefault?: boolean. Kumbki lipp kirjeldab vastavat teksti: true tähendab lokaliseeritud toote vaikimisi teksti, false aga kohandatud stringi, mis tuleb säilitada. Puuduv lipp, sealhulgas vanemates vastustes, tähendab, et teksti päritolu pole teada; ärge kunagi järeldage päritolu teksti vaikimisi tekstiga võrdlemise põhjal. Väljade olemasolu sõltub backendi, mitte SDK versioonist. Avaldatud SDK 0.1.4 ei deklareeri neid lippe tõeväärtusväljadena, kuid selle Record<string, unknown> tüüp ja muutmata JSON-vastuse edastamine võimaldavad tarbijal lipu olemasolul selle väärtuse turvaliselt kitsendada. Edukaid vastuseid ei valideerita ega teisendata käitusajal väljade kaupa.
Täielikult kohandatud kasutajaliides võib neid eirata. Hoidke iga külastaja conversationId-i tema brauseris või seansi olekus; ärge jagage kunagi üht globaalset vestluse ID-d. SDK ei saada lehekonteksti (sourceUrl või sourcePath) ega mudelivalikuid. Peata sendMessage() ei paku voogedastust, automaatseid korduskatseid, timeout’i, AbortSignal-i valikut, salvestust ega UI-olekut. Kohandatud fetch-i abil saab transpordipoliitikat ise rakendada. Peata chati puhul korduskatseid ei tehta; avaldatud SDK 0.1.4 proovib getWidgetConfig()-i ainult ühe korra uuesti pärast HTTP 400 ning hostitud v15 kordab käivituse GET-päringuid. Avalikus vastuses pole eraldi wasAnswered- ega varuvastuse oleku välja.
getWidgetConfig() tagastab Promise<WidgetConfig> ja kasutab päist Authorization: Bearer. SDK 0.1.4 kordab ainult HTTP 400 järel päringut ühe korra URL-kodeeritud võtmega päringustringis; muid olekuid ei korrata. WidgetConfig on Record<string, unknown> valikuliste tüübitud lubatuse, värvide, asukoha, pealkirja, tervituse, brändingu, ikoonide ja lokaadi väljadega. Tundmatuid lisavälju tuleb enne kasutamist kitsendada. Praegused serveriväljad ja vaikeväärtused leiate hostitud vidina juhendist. Edukas konfiguratsioonipäring märgib projekti ka vidinaga paigaldatuks, isegi kui kohandatud klient vidinat ei kuva.
getWidgetTranslations(locale) tagastab Promise<WidgetTranslations> väljadega translations: Record<string, string>, dir: 'ltr' | 'rtl' ja serveri valitud locale: string. Avalik lõpp-punkt ei kasuta API-võtit ega projekti lokaadiseadeid. Toetatud koodid on en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy ja cs. SDK URL-kodeerib lokaadi, kuid ei normaliseeri seda: fr-CA ja FR annavad 400; tühi string valib serveris inglise keele. Praegused kataloogid on vasakult paremale ja neid saab tund aega vahemällu salvestada.
Kohandatud kasutajaliideses valige lokaat ise ning hostitud käitumise jäljendamisel arvestage allowLocaleOverride-i ja projekti fikseeritud või automaatrežiimi; puuduvate tõlkevõtmete jaoks pakkuge varuteksti. Need seaded juhivad kasutajaliidese silte; praeguse lähtekoodi peata klient saab toote enda varusõnumite jaoks eraldi määrata uiLocale-i. Kumbki ei taga AI vastuste kvaliteeti ega keelt.
Korduskatsete ohutus
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.
Määrake igale loogilisele sõnumile ainulaadne idempotencyKey ja säilitage korduskatseks täpselt sama sisend, sealhulgas algne conversationId. SDK saadab võtme päises Idempotency-Key, kuid ei loo seda ega korda päringut teie eest. Võti on projektipõhine ja peab sisaldama 1–128 märki, mis vastavad mustrile [A-Za-z0-9][A-Za-z0-9._:-]*. Identse lõpule viidud päringu korral saab tagastada salvestatud vastuse ja markeri (kui see oli olemas), päringut uuesti käivitamata; muudetud sisend, pooleliolev päring või lõplik tõrge võib anda 409. Praegune server kaasab päringu sõrmejälge normaliseeritud lokaadi; säilitage algne uiLocale, sealhulgas selle algne puudumine. Ärge korrake pimesi iga 409 vastust ega looge ebaselge transporditõrke järel uut võtit.
Kordusesitus ei ole püsiv: lõpetatud ja ebaõnnestunud kirjed aeguvad 24 tundi pärast reserveerimist, kuid ootel kirjeid ei vabastata üksnes aja möödumisel. Pärast lõppolekus kirje aegumist võib korduskatse uuesti käivituda. Piirake korduskatsete ajavahemikku ja uurige püsivaid konflikte, selle asemel et eeldada piiramatut deduplikeerimist.
Järgmised sammud
- Eelistate hallatavat ehituseta kasutajaliidest? Installige
widget.js. - Kohandage hostitud kasutajaliidest jaotises Hostitud vidina kohandamine.
- Testige enne käivitamist varuvastuseid, allikaviiteid ja mobiilikäitumist käivituseelse kontrollnimekirja abil. Kui lülitate origin’i piirangu sisse, testige ka täpseid origin’e.