Neidio i'r prif gynnwys

SDK JavaScript

:::note Statws fersiwn Mae'r SDK npm 0.1.4 cyhoeddedig yn dilysu baseUrl, yn amlapio corff ymateb na ellir ei ddarllen, ac yn ailgeisio config HTTP 400 unwaith yn unig. Gyda widget.js v15 mae teardown remove()/window.ChattyBox.destroy() ar gael; nid yw headless sendMessage() yn ailgeisio’n awtomatig.

Nid yw'r SDK 0.1.4 cyhoeddedig yn cefnogi uiLocale. Mae'r ymddygiad locale a ddisgrifir isod ar gyfer y ffynhonnell gyfredol yn unig; nid yw'n honiad am yr SDK cyhoeddedig na fersiwn gyhoeddedig y widget lletyol. :::

Y pecyn npm yw’r ffordd a argymhellir i integreiddio ChattyBox. Ffurfweddwch un cleient a llwythwch y widget arnofiol a gynhelir o gynllun porwr parhaus, neu defnyddiwch y dulliau di-ben gyda’ch cydrannau eich hun.

Cychwyn Cyflym​

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

// Cadwch y loader am oes y dudalen, gan gynnwys llywio SPA.

Galwch mountWidget() ar ôl i document.body fodoli, nid wrth rendro nac SSR. Caiff y widget ei ychwanegu o dan document.body, nid yn eich cydran; mae { locale: 'fr' } yn gofyn am locale cychwynnol yn unig, ac mae'n gweithio dim ond os caniateir diystyru locale sgript gan y prosiect.

Enwau enghreifftiol yw import.meta.env.PUBLIC_*. Defnyddiwch gonfensiwn cyfluniad cyhoeddus eich fframwaith, megis import.meta.env.VITE_* yn Vite neu process.env.NEXT_PUBLIC_* yn Next.js. Yn Node.js, darllenwch a dilyswch werthoedd process.env yn lle hynny.

Cael Eich Ffurfweddiad Cyhoeddus​

  1. Crëwch brosiect a mynegeiwch eich cynnwys.
  2. Profwch gwestiynau cynrychioliadol yn Profi'r sgwrsfot.
  3. O dan Gosod → Allweddi a pharthau, archwiliwch neu crëwch allwedd porwr gyhoeddus a gwiriwch ei gosodiadau tarddiad. Mae allweddi heb gyfyngiadau’n gweithio ar draws tarddiadau; gall allwedd a baratowyd ar gyfer gwefan fod wedi’i chyfyngu eisoes.
  4. O dan Gosod → Gosod ar wefan, rhowch URL gwefan HTTP(S), dewiswch allwedd addas a chopïwch URL API y widget o’r pyt. Mae’r dewiswr yn cynnig allweddi sydd heb ddod i ben ac sydd heb gyfyngiad neu wedi’u caniatáu ar gyfer tarddiad yr URL. Rhowch darddiad a ganiateir i ddewis allwedd gyfyngedig, ac archwiliwch y cyfyngiadau drwy Rheoli allweddi a pharthau a ganiateir. Os nad yw’r ffurflen ar gael, cwblhewch y cam paratoi a ddangosir yn y dangosfwrdd yn gyntaf.

Mae allweddi API widget cyhoeddus wedi’u cynllunio i ymddangos mewn cod porwr. Maent yn nodi prosiect ond nid ydynt yn fanylion rheoli. O dan Gosod → Allweddi a pharthau → Golygu tarddiadau gallwch alluogi cyfyngiadau tarddiad dewisol fel amddiffyniad ychwanegol. Maent yn paru cynllun, enw gwesteiwr a phorth, nid llwybrau nac wildcard subdomains, ac nid ydynt yn ddilysu. Mae’r pecyn yn gleient ESM ar gyfer rhaglenni Node.js cyfredol a phorwyr sy’n darparu fetch.

Mae'r API yn defnyddio Origin y cais neu, fel dewis wrth gefn, darddiad Referer. Mae tarddiad coll neu nas caniateir ar allwedd gyfyngedig yn dychwelyd 401 Invalid API key, fel allwedd annilys neu sydd wedi dod i ben. Nid yw Node.js fetch yn anfon y penawdau porwr hyn yn awtomatig. Nid yw gwiriadau tarddiad yn atal cleient nad yw'n borwr rhag ffugio penawdau.

Constructor ac allforion​

Mae new Chattybox(options) yn gofyn am apiKey cyhoeddus nad yw'n wag a baseUrl nad yw'n wag. Yn SDK 0.1.4, rhaid i baseUrl fod yn URL HTTP(S) absoliwt heb gymwysterau, llinyn ymholiad na fragment. Gellir darparu gweithrediad fetch cydnaws yn ddewisol; fel arall defnyddir fetch byd-eang. Defnyddiwch URL API HTTP y widget o'r pyt gosod, nid URL y dangosfwrdd nac URL cleient Convex .cloud. Tynnir slashiau terfynol ac yna ôl-ddodiad /chat; mae apiKey a'r baseUrl wedi'i normaleiddio ar gael fel priodweddau darllen-yn-unig.

Mae'r constructor yn taflu Error arferol os yw'r opsiynau neu'r gwerthoedd gofynnol yn annilys, os nad yw fetch a ddarperir yn ffwythiant, neu os yw'r URL yn annilys. Mae'r pecyn yn allforio Chattybox, ChattyboxError a'r mathau ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions a HostedWidgetHandle. Nid oes cydran na hooks React. Mae bwndel IIFE ./browser yn darparu'r ddau constructor ar window.ChattyboxSDK; nid yw ei lwytho ar ei ben ei hun yn atodi UI.

Atodi’r Widget Lletyol o’r Cod​

Defnyddiwch hwn pan fyddwch eisiau rhyngwyneb ChattyBox a gynhelir, gan reoli o god eich rhaglen ble mae’n cael ei atodi:

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

// Defnyddiwch widget.remove() ar gyfer teardown bwriadol.

Mae mountWidget(options?) yn dychwelyd handlen yn syth, cyn i'r sgript lwytho neu i'r UI fod yn barod. Yn SDK cyhoeddedig 0.1.4, mae mountiau unfath yn rhannu'r sgript ac mae gan bob handlen gyfeiriad: mae remove() yn idempotent, ac mae'r handlen olaf yn anfon signal tynnu cyn dileu'r sgript. Gyda widget.js v15 lletyol, mae'r signal yn canslo cychwyn, ailgeisiadau a chat sy'n rhedeg, ac yn tynnu UI, arddulliau, dolenni ffont a'r API byd-eang sy'n perthyn i'r widget. Gwrthodir allwedd, URL API, scriptUrl, locale neu opsiwn debug gwahanol tra bo handlenni'n bodoli. Gyda widget.js v15, mae window.ChattyBox.destroy() yn darparu teardown lletyol cyfatebol. Peidiwch â chymysgu'r SDK â GTM, ategyn neu loader arall; nid oes ready promise, container target na diweddariad locale adweithiol.

Mae scriptUrl yn rhagosod i https://chattybox.ai/widget.js; defnyddiwch URL arall ar gyfer loader rhagolwg dibynadwy neu un a gynhelir gennych yn unig. Mae locale nad yw'n wag yn gosod data-locale os yw polisi'r prosiect yn caniatáu hynny; mae debug gwir yn gosod data-debug="true". Mae handle.element yn cyfeirio at yr elfen sgript. Mae fetch personol y constructor ar gyfer dulliau di-ben yn unig, nid y widget lletyol. Ni all glanhau ddadwneud cais a broseswyd eisoes gan y gweinydd. Mae glanhau llawn yn gofyn am y widget.js wedi'i ddiweddaru hefyd; diweddarwch gopi hunan-letyol ar wahân. Nid yw'r SDK yn canfod sgriptiau â llaw heb y marciwr.

Mae loader lletyol v15 yn ailgeisio methiannau trosglwyddo, cyrff ymateb llwyddiannus yr amharwyd arnynt, ymatebion sydd ar y gweill, terfynau cyfradd a gwallau gweinydd gyda'r un corff ac allwedd idempotency. Mae'n gwneud uchafswm o 10 ymgais ac nid yw'n amserlennu ailgais awtomatig y tu hwnt i 30 eiliad; mae oedi Retry-After darllenadwy yn cyfrif tuag at y cyfnod hwnnw. Ar ôl hynny, mae Retry message yn ailddefnyddio'r cais rhesymegol; mae cwestiwn newydd yn dechrau cais newydd. Mae JSON annilys neu siâp ymateb annilys ar ymateb llwyddiannus yn wall protocol terfynol, nid yn ailgais awtomatig. Rhaid i ymatebion API traws-darddiad ddatgelu Retry-After drwy Access-Control-Expose-Headers.

Adeiladu Eich UI Eich Hun​

Defnyddiwch y dulliau di-ben isod pan mai eich rhaglen sy’n berchen ar restr negeseuon, mewnbwn, cyflwr llwytho a gwallau, dyfyniadau a hygyrchedd.

Anfon Neges​

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

Gosodwch PUBLIC_CHATTYBOX_API_URL i union URL API y widget o Gosod ar wefan. Mae’r SDK yn derbyn naill ai wraidd y deployment neu URL sy’n gorffen â /chat.

Mae’r ymateb yn cynnwys:

MaesMathDisgrifiad
messagestringAteb neu fallback wedi'i ffurfweddu; rendrwch fel testun neu Markdown wedi'i lanhau, nid HTML crai.
conversationIdstringDynodwr a ddefnyddir i barhau’r sgwrs hon.
sourcesstring[]URLau ffynhonnell; gall y rhestr fod yn wag ar gyfer fallback. Dilyswch URLau HTTP(S) cyn rendro dolenni.
providerErrorstring (dewisol, ffynhonnell gyfredol)Cod methiant darparwr strwythuredig y gellir ei ddychwelyd pan fydd darparwr yn methu; nid yw'n ymddangos mewn atebion arferol na negeseuon wrth gefn sydd wedi'u ffurfweddu. Triniwch godau anhysbys fel methiant cyffredinol.
productFallback'no_context_ui' | 'no_context_question' (dewisol, ffynhonnell gyfredol)Yn nodi copi dim-cyd-destun sy'n perthyn i'r cynnyrch a sut y dewiswyd ei iaith; gweler isod.

Mae sendMessage(input) yn dychwelyd Promise<ChatResponse> ac yn derbyn message, conversationId dewisol neu null, ac idempotencyKey dewisol. Yn y ffynhonnell gyfredol, mae hefyd yn derbyn uiLocale?: string; nid yw'r maes hwn ar gael yn SDK npm 0.1.4 cyhoeddedig. Mae'r SDK cyfredol yn trosglwyddo locale a ddarparwyd i'r gweinydd heb ei newid, ac yn hepgor y maes os yw'n absennol neu'n undefined; nid yw'r SDK yn canfod locale yn awtomatig. Mae'r gweinydd yn dilysu uiLocale ac yn ei normaleiddio i iaith sylfaenol a gefnogir. Mae gwerthoedd annilys neu heb eu cefnogi yn dychwelyd HTTP 400 Invalid uiLocale, yn hytrach na disgyn yn ôl yn dawel. Cyd-destun cyflwyno a ddarperir gan y galwr yw locale, nid rheolydd dilysu nac awdurdodi. Mae'r SDK yn anfon yr allwedd API gyhoeddus yng nghorff JSON, ond nid yw'n anfon sourceUrl, sourcePath na dewisiadau model. Dilyswch neges nad yw'n wag a hyd trimiedig uchaf o 2,000 nod cyn ei hanfon; mae'r backend yn gorfodi'r terfyn ond mae methiannau dilysu mewnol yn ymddangos fel HTTP 500 cyffredinol ar hyn o bryd.

Er enghraifft, gyda'r SDK a'r backend cyfredol, defnyddiwch chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). Mae signal iaith y cwestiwn yn cael blaenoriaeth dros uiLocale ar gyfer negeseuon wrth gefn sy'n perthyn i'r cynnyrch. Os yw'r canfod yn amhendant neu'n dibynnu ar heuristig Saesneg ASCII yn unig, gall locale UI bennu iaith y negeseuon hynny; heb y naill na'r llall, defnyddir y rhagosodiadau cynnyrch. Defnyddir neges wrth gefn a ysgrifennwyd gan y prosiect yn union fel y mae, yn lle'r neges wrth gefn cynnyrch heb gyd-destun. Nid yw locale UI yn cyfieithu testun wrth gefn a ysgrifennwyd gan y prosiect nac yn newid allbwn a gynhyrchir gan AI; nid yw'n gwarantu ansawdd ateb nac iaith yr ateb.

Mae API cyfredol y widget/sgwrs yn ychwanegu productFallback at ymatebion dim-cyd-destun sy'n perthyn i'r cynnyrch yn unig; mae argaeledd yn dibynnu ar fersiwn y backend, nid fersiwn yr SDK. Mae no_context_ui yn golygu bod iaith y neges wrth gefn wedi'i dewis o locale UI/rhagosodedig neu nad oedd modd ei phennu; gall UI personol ei hail-leoleiddio gan ddefnyddio cofnod cyfredol message.noContext yn y catalog. Mae no_context_question yn golygu bod y dosbarthydd presennol wedi adnabod iaith y cwestiwn; cadwch destun y neges a ddychwelwyd. Nid yw hyn yn profi bod yr iaith wedi'i hadnabod yn gywir—nid yw'r dosbarthydd bob amser yn gywir. Nid yw'r marcwr yn bresennol ar gyfer negeseuon wrth gefn personol, atebion arferol, methiannau darparwr nac ymatebion etifeddol. Peidiwch â chasglu tarddiad y neges o'i thestun na'i gydraddoldeb â thestun arall, nac o absenoldeb y marcwr; anwybyddwch godau productFallback anhysbys.

Nid yw SDK 0.1.4 cyhoeddedig yn datgan productFallback yn ChatResponse, ond mae'n trosglwyddo'r maes yn y gwrthrych JSON a ddychwelir os bydd y backend yn ei ddarparu. Gwiriwch y gwerth yn ddiogel cyn ei ddefnyddio. Gall ailchwarae cais idempotency gadw'r neges wreiddiol a'r marcwr, os oes un. Nid oes maes cyffredinol wasAnswered na maes statws fallback, felly peidiwch â dyfeisio canlyniad strwythuredig nad yw'n cael ei gefnogi.

Nid yw sendMessage() di-ben yn darparu ffrydio, ailgeisiadau awtomatig, terfynau amser, opsiwn AbortSignal, storfa na chyflwr UI. Gall fetch personol ddarparu polisi trosglwyddo. Ar wahân i sgwrs ddi-ben, mae SDK 0.1.4 yn ailgeisio getWidgetConfig() unwaith yn unig ar ôl HTTP 400, ac mae loader lletyol v15 yn ailgeisio ei geisiadau GET cychwynnol.

Parhau â Sgwrs​

Cadwch ID y sgwrs a ddychwelwyd yng nghyflwr eich UI a’i anfon gyda’r neges nesaf:

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

Peidiwch ag ailddefnyddio un ID sgwrs ar gyfer ymwelwyr nad ydynt yn gysylltiedig. Mae hepgor conversationId neu ddefnyddio null yn dechrau sgwrs newydd. Mae’r ID yn grwpio negeseuon a gedwir; wrth ailddefnyddio'r un conversationId, mae'r model yn derbyn hyd at 12 neges ddiweddar a gedwir, pob un wedi'i byrhau i 2,000 nod. Cyd-destun cyfyngedig yw hwn, nid y trawsgrifiad llawn na chof parhaol; ailadroddwch fanylion hŷn pan fo angen.

Diogelwch ailgeisio​

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.

Darparwch idempotencyKey unigryw ar gyfer pob neges resymegol a chadwch yr union fewnbwn ar gyfer ailgais. Mae allweddi wedi'u cwmpasu i'r prosiect a rhaid iddynt fod yn 1–128 nod sy'n cyfateb i [A-Za-z0-9][A-Za-z0-9._:-]*. Gellir ailchwarae cais unfath sydd wedi'i gwblhau gyda'i neges a'i farcwr gwreiddiol, os oes un, heb ei ailredeg; gall mewnbwn wedi'i newid, cais sydd ar y gweill neu fethiant terfynol ddychwelyd 409. Peidiwch â chynhyrchu allwedd newydd ar ôl methiant trosglwyddo ansicr.

Nid yw ailchwarae'n barhaol: daw cofnodion wedi'u cwblhau a methiannau i ben 24 awr ar ôl eu cadw, ond nid yw cofnodion sydd yn yr arfaeth yn cael eu hadennill ar sail amser yn unig. Gall ailgais ar ôl i gofnod terfynol ddod i ben redeg eto. Cadwch gyfnodau ailgeisio'n gyfyngedig ac ymchwiliwch i wrthdaro parhaus.

Trin Gwallau​

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

Mae ChattyboxError.status yn cynnwys statws HTTP ac mae code yn ddewisol; ni chaiff gwallau rhwydwaith eu lapio. Mae'r SDK yn anfon idempotencyKey fel Idempotency-Key ond nid yw'n creu un nac yn ailgeisio i chi. Cadwch yr un allwedd unigryw a'r un mewnbwn ar gyfer retry; peidiwch ag ailgeisio pob 409 yn ddall.

Mae code yn bresennol dim ond os yw'r API yn dychwelyd code llinyn; nid yw'r rhan fwyaf o wallau API widget cyfredol yn gwneud hynny. Mae ymatebion nad ydynt yn 2xx, llinyn error nad yw'n wag hyd yn oed gyda HTTP 200, JSON annilys a JSON nad yw'n wrthrych yn taflu ChattyboxError. Mae SDK 0.1.4 hefyd yn lapio corff ymateb na ellir ei ddarllen gyda RESPONSE_BODY_READ_FAILED. Nid yw gwrthrychau JSON llwyddiannus yn cael eu dilysu fesul maes. Mae statysau cyffredin yn cynnwys 400 ar gyfer mewnbwn neu locale cyfieithu annilys, 401 ar gyfer allwedd/tarddiad, 403 ar gyfer widget anabl gan gynnwys sgwrs ddi-ben, 409 ar gyfer gwrthdaro idempotency, 413 ar gyfer corff sgwrs dros 65,536 beit, 429 ar gyfer terfyn cyfradd a 500 ar gyfer gwallau mewnol. Nid yw'r SDK yn datgelu penawdau ymateb ar ei ganlyniad na'i wall.

Ar gyfer cais ailgeisio, cadwch yr union fewnbwn gwreiddiol, gan gynnwys uiLocale a ddarparwyd (neu'r ffaith iddo gael ei hepgor), ynghyd â'r conversationId gwreiddiol. Mae'r gweinydd cyfredol yn cynnwys y locale wedi'i normaleiddio yn fingerprint y cais idempotency; gall mewnbwn wedi'i newid gyda'r un allwedd achosi gwrthdaro.

Ailddefnyddio Gosodiadau Prosiect a Chyfieithiadau​

Mae’r SDK hefyd yn darparu getWidgetConfig() a getWidgetTranslations(locale). Mae’r dulliau hyn yn cefnogi cleientiaid sydd am atgynhyrchu gosodiadau prosiect a labeli lleol y widget lletyol:

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

Gall UI cwbl bersonol eu hanwybyddu. Cadwch conversationId pob ymwelydd ym mhorwr neu gyflwr sesiwn yr ymwelydd hwnnw; peidiwch byth â rhannu un ID sgwrs byd-eang. Mae getWidgetTranslations(locale) yn derbyn un o'r 14 cod catalog; nid yw fr-CA na FR yn cael eu normaleiddio gan yr SDK fel y mae loader y widget yn y ffynhonnell gyfredol yn ei wneud.

Mae getWidgetConfig() yn dychwelyd Promise<WidgetConfig> ac yn defnyddio Authorization: Bearer. Mae SDK 0.1.4 yn ailgeisio unwaith gydag allwedd wedi'i hamgodio yn y llinyn ymholiad dim ond ar ôl HTTP 400; nid yw'n ailgeisio statysau eraill. Mae WidgetConfig yn Record<string, unknown> gyda phriodweddau dewisol wedi'u teipio ar gyfer galluogi, lliwiau, safle, testun, brandio, eiconau a gosodiadau locale. Gwiriwch fathau meysydd anhysbys cyn eu defnyddio; gweler addasu'r widget lletyol am feysydd a rhagosodiadau. Mae cais ffurfweddu llwyddiannus hefyd yn nodi bod y widget wedi'i osod, hyd yn oed os nad yw cleient personol yn rendro widget.

Mae getWidgetTranslations(locale) yn dychwelyd Promise<WidgetTranslations> gyda translations: Record<string, string>, dir: 'ltr' | 'rtl' a'r locale a ddewiswyd gan y gweinydd. Mae'r endpoint yn gyhoeddus ac nid yw'n defnyddio'r allwedd API na gosodiadau locale'r prosiect. Defnyddiwch un o en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy neu cs; mae fr-CA a FR yn dychwelyd 400, ac mae llinyn gwag yn dewis Saesneg. Mae pob catalog cyfredol yn LTR a gellir ei storio mewn cache am awr.

Ar gyfer UI personol, datryswch y locale eich hun, parchwch allowLocaleOverride a gosodiadau fixed/auto os ydych yn atgynhyrchu ymddygiad y widget, a darparwch ddewisiadau wrth gefn ar gyfer allweddi cyfieithu coll. Mae'r gosodiadau hyn yn rheoli labeli UI; gall cleient di-ben y ffynhonnell gyfredol ddarparu uiLocale ar wahân ar gyfer negeseuon wrth gefn y cynnyrch. Nid yw'r naill na'r llall yn gwarantu ansawdd nac iaith atebion a gynhyrchir gan AI.

Mae teipiau ffynhonnell gyfredol y SDK yn cynnwys headerTitleIsDefault?: boolean a welcomeMessageIsDefault?: boolean ar WidgetConfig. Mae pob baner yn disgrifio ei thestun cyfatebol: mae true yn golygu mai rhagosodiad cynnyrch wedi'i leoleiddio yw'r testun, tra bo false yn golygu mai llinyn personol ydyw y dylid ei gadw. Mae baner absennol, gan gynnwys mewn ymatebion hŷn, yn golygu nad yw tarddiad y testun yn hysbys; peidiwch byth â chymharu'r testun â rhagosodiad i gasglu ei darddiad. Mae argaeledd yn dibynnu ar fersiwn y backend, nid fersiwn yr SDK. Nid yw SDK 0.1.4 cyhoeddedig yn datgan y baneri hyn fel gwerthoedd booleaidd, ond mae ei fath Record<string, unknown> a'r ymateb JSON heb ei newid yn galluogi defnyddwyr i gulhau'r math yn ddiogel pan ddarperir y baneri. Nid yw ymatebion llwyddiannus yn cael eu dilysu na'u gorfodi i fathau penodol fesul maes.

Camau Nesaf​