SDK JavaScript
:::note Stato delle versioni
L’SDK npm pubblicato 0.1.4 convalida baseUrl, incapsula corpi di risposta illeggibili e ritenta config HTTP 400 una sola volta. Con widget.js v15, remove()/window.ChattyBox.destroy() supporta il teardown; sendMessage() headless non ritenta automaticamente.
:::
Il pacchetto npm è il modo consigliato per integrare ChattyBox dal codice dell’applicazione. Configura la chiave pubblica e l’URL API, poi carica il widget flottante gestito da un layout persistente nel browser oppure usa i metodi headless con i tuoi componenti. L’SDK pubblicato 0.1.4 include le correzioni del ciclo di vita e delle dichiarazioni per NodeNext in modalità rigorosa. La pulizia completa del widget richiede anche il widget.js gestito aggiornato; nelle installazioni self-hosted il file va aggiornato separatamente.
Avvio rapido
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();
// Mantieni questo loader per la vita della pagina, anche nella navigazione SPA.
Chiama mountWidget() nel browser dopo che esiste document.body, non durante il rendering o sul server. Il widget flottante viene aggiunto sotto document.body, non dentro il componente. Puoi passare { locale: 'fr' } per richiedere il francese all’inizializzazione, se il progetto consente gli override dello script.
I nomi import.meta.env.PUBLIC_* negli esempi sono illustrativi. Usa la convenzione pubblica del tuo framework, ad esempio import.meta.env.VITE_* in Vite o process.env.NEXT_PUBLIC_* in Next.js; in Node.js leggi e convalida i valori di process.env.
Ottieni la configurazione pubblica
- Crea un progetto e indicizza i contenuti.
- Prova domande rappresentative in Prova il chatbot.
- In Installa → Chiavi e domini, controlla o crea una chiave pubblica per il browser e verifica le impostazioni delle origini. Le chiavi create senza restrizioni funzionano su origini diverse; una chiave preparata per un sito potrebbe essere già limitata.
- In Installa → Installazione sul sito web, inserisci un URL HTTP(S), seleziona una chiave adatta e copia l’URL API del widget mostrato nello snippet. Il selettore mostra le chiavi non scadute senza restrizioni o consentite per l’origine dell’URL. Per una chiave limitata inserisci un’origine consentita e verifica le restrizioni tramite Gestisci chiavi e domini consentiti. Se il modulo non è disponibile, completa prima il passaggio di configurazione mostrato nella dashboard.
Le chiavi API pubbliche del widget sono pensate per comparire nel codice del browser. Identificano un progetto, ma non sono credenziali di gestione. Per un rafforzamento facoltativo, usa Installa → Chiavi e domini → Modifica origini per consentire le origini esatte necessarie. Le restrizioni non sono autenticazione; con una chiave limitata, una richiesta senza origine consentita riceve 401 Invalid API key. Il pacchetto è un client ESM per applicazioni Node.js e browser moderni che forniscono fetch.
Le restrizioni confrontano schema, hostname e porta normalizzati, non percorsi o sottodomini wildcard. L’API usa Origin e, in alternativa, l’origine di Referer; anche una chiave non valida o scaduta restituisce 401 Invalid API key. Il fetch di Node.js non invia automaticamente questi header del browser. Un client non browser può falsificare gli header, quindi il controllo dell’origine non autentica i visitatori.
Costruttore ed esportazioni
new Chattybox(options) richiede apiKey, una chiave pubblica non vuota, e baseUrl, un URL HTTP(S) assoluto non vuoto senza credenziali, query string o frammento nell’SDK 0.1.4. L’opzione fetch può fornire un’implementazione compatibile; altrimenti viene usato il fetch globale. Copia l’URL HTTP dell’API widget dallo snippet di installazione, non l’URL della dashboard o l’URL client Convex .cloud. L’SDK rimuove le barre finali e poi l’eventuale suffisso /chat; espone apiKey e baseUrl normalizzato come proprietà di sola lettura.
Il costruttore genera un normale Error se le opzioni mancano o non sono un oggetto, se apiKey o baseUrl manca, non è una stringa o è vuoto, se il fetch fornito non è una funzione o se baseUrl non rispetta i requisiti. Il pacchetto esporta Chattybox, ChattyboxError e i tipi ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions e HostedWidgetHandle. Non include componenti o hook React. Il bundle IIFE ./browser espone i due costruttori su window.ChattyboxSDK, ma il solo caricamento non monta l’interfaccia.
Monta il widget ospitato dal codice
Usa questa soluzione quando vuoi inizializzare dal codice dell’applicazione l’interfaccia flottante gestita da 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({ locale: 'fr', debug: false });
mountWidget() restituisce un handle prima che script o UI siano pronti. Nell’SDK pubblicato 0.1.4, mount identici condividono lo script e ogni handle mantiene un riferimento: remove() è idempotente e l’ultimo handle segnala la rimozione. Con widget.js v15, questo annulla inizializzazione, retry e chat in corso e rimuove UI, stili, link ai font, script e API globale; window.ChattyBox.destroy() esegue lo stesso teardown. Una chiave, URL API, scriptUrl, locale o opzione debug diversa viene rifiutata finché esistono handle. L’SDK pubblicato 0.1.4 non offre una promise ready, un target contenitore o un’API per aggiornare la locale in modo reattivo. Il loader della sorgente attuale osserva le modifiche dirette a data-locale; verifica la versione distribuita prima di fare affidamento su questo comportamento. Scegli un solo loader.
L’handle viene restituito in modo sincrono e element contiene l’elemento script inserito o riutilizzato. scriptUrl usa per impostazione predefinita https://chattybox.ai/widget.js: modificalo solo per un loader di anteprima attendibile o self-hosted. locale non vuoto imposta data-locale se il progetto consente l’override; debug attiva data-debug="true" solo se truthy. L’SDK non rileva loader manuali privi dell’attributo di identificazione: non combinare il mount SDK con plugin, tag GTM o script separati sulla stessa pagina. Il fetch personalizzato del costruttore vale solo per i metodi headless, non per il widget ospitato.
Per la pulizia di un componente o la revoca del consenso, rimuovi ogni handle corrispondente; prima di cambiare progetto o lingua rimuovi il mount precedente. Mantieni il loader nella shell persistente durante la normale navigazione. Il teardown non può annullare una richiesta già elaborata dal server.
Il loader ospitato v15 riprova errori di trasporto, corpi di risposte riuscite interrotti, risposte ancora in corso, limiti di frequenza ed errori del server con lo stesso corpo e la stessa chiave di idempotenza. Esegue al massimo 10 tentativi e non pianifica retry automatici oltre 30 secondi; i ritardi Retry-After leggibili rientrano nel budget. Dopo l’esaurimento, Riprova messaggio riusa la richiesta logica; una nuova domanda ne avvia una nuova. JSON non valido o una struttura di risposta non valida in una risposta riuscita costituiscono un errore di protocollo terminale, non un retry automatico. Le risposte API cross-origin devono esporre Retry-After tramite Access-Control-Expose-Headers.
Crea la tua interfaccia
Usa i metodi headless seguenti quando l’applicazione gestisce direttamente l’elenco dei messaggi, l’input, gli stati di caricamento ed errore, le citazioni e l’accessibilità.
Invia un messaggio
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);
Imposta PUBLIC_CHATTYBOX_API_URL sull’URL API esatto del widget indicato nello snippet di Installazione sul sito web. L’SDK accetta la radice del deployment oppure un URL che termina con /chat.
La risposta contiene:
| Campo | Tipo | Descrizione |
|---|---|---|
message | string | Testo della risposta o messaggio di fallback configurato. Visualizzalo come testo o Markdown sanificato, mai come HTML non sanificato. |
conversationId | string | Identificatore usato per continuare questa conversazione. |
sources | string[] | URL delle fonti della risposta; può essere vuoto in caso di fallback. Verifica che gli URL siano HTTP(S) prima di renderizzare i link. |
providerError | string (opzionale, sorgente attuale) | Codice strutturato di errore del provider. Non è presente nelle risposte normali o nei fallback configurati; tratta i codici sconosciuti come errori generici. |
productFallback | 'no_context_ui' | 'no_context_question' (opzionale, sorgente attuale) | Indica i messaggi senza contesto gestiti dal prodotto e come ne è stata scelta la lingua; vedi sotto. |
sendMessage(input) restituisce Promise<ChatResponse>. SendMessageInput accetta message: string (obbligatorio), conversationId: string | null e idempotencyKey: string (opzionali). La versione dell’SDK nella sorgente attuale accetta anche uiLocale: string opzionale; questa opzione non è disponibile nell’SDK npm pubblicato 0.1.4. L’SDK della sorgente attuale inoltra il valore fornito senza modificarlo e omette il campo se assente o undefined; non rileva automaticamente la lingua. Il backend della sorgente attuale convalida e normalizza la locale a una lingua base supportata. Un valore malformato o non supportato restituisce HTTP 400 Invalid uiLocale, senza fallback silenzioso. uiLocale è un contesto di presentazione fornito dal chiamante, non un controllo di autenticazione o autorizzazione.
L’SDK invia la chiave API pubblica nel corpo JSON, ma non invia il contesto della pagina (sourceUrl o sourcePath) né opzioni del modello. sendMessage() non offre streaming, retry automatici, timeout, un’opzione AbortSignal, archiviazione o stato UI; un fetch personalizzato può definire la policy di trasporto. Questa assenza di retry riguarda la chat headless: l’SDK 0.1.4 riprova getWidgetConfig() una sola volta dopo HTTP 400 e il loader ospitato v15 riprova le richieste GET iniziali.
Prima dell’invio verifica che il messaggio non sia vuoto e non superi 2.000 caratteri dopo la rimozione degli spazi iniziali e finali. Il backend applica questo limite, ma attualmente gli errori della sua convalida interna appaiono come HTTP 500 generici.
Ad esempio, con l’SDK e il backend della sorgente attuale, puoi usare chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }).
Per i messaggi di fallback del prodotto, un segnale riconosciuto della lingua della domanda ha la precedenza su uiLocale. Se il rilevamento non è conclusivo o si basa soltanto sull’euristica inglese per testi ASCII, la locale UI può determinare la lingua del fallback; in assenza di entrambi si applicano i valori predefiniti del prodotto. Un fallback scritto dal progetto viene usato così com’è al posto del fallback di prodotto senza contesto. uiLocale non traduce il testo del fallback personalizzato e non modifica le risposte generate dall’AI, né garantisce la qualità o la lingua della risposta.
L’API widget/chat della sorgente attuale aggiunge productFallback solo alle risposte senza contesto con testo gestito dal prodotto; la disponibilità dipende dalla versione del backend, non da quella dell’SDK. no_context_ui indica che la lingua del fallback è stata scelta in base alla locale UI o predefinita, oppure non è stata determinata; un’interfaccia personalizzata può sostituire il testo con quello localizzato indicato dalla voce corrente message.noContext del catalogo. no_context_question indica che il classificatore esistente ha riconosciuto la lingua della domanda: conserva il testo restituito in message. Non è garantito che il classificatore identifichi correttamente la lingua. Il marker non è presente nei fallback personalizzati, nelle risposte normali, negli errori del provider o nelle risposte legacy. Non dedurre la provenienza dal testo di message né dall’assenza del marker e ignora i valori sconosciuti di productFallback.
L’SDK npm pubblicato 0.1.4 non dichiara productFallback in ChatResponse, ma inoltra il campo nell’oggetto JSON restituito se il backend lo fornisce. Verifica in modo sicuro che il valore corrisponda a uno dei valori noti prima di usarlo. Non esiste un campo generale wasAnswered o di stato del fallback: non inventare un risultato strutturato di risposta non supportata.
Se ripeti una richiesta con la stessa chiave di idempotenza, conserva esattamente gli input originali, compreso uiLocale (anche se era stato omesso): il backend attuale include la locale normalizzata nell’impronta della richiesta. Una richiesta completata e identica può essere ripetuta con il replay del messaggio e del marker originali memorizzati, se presenti, senza rieseguire la richiesta.
Continua una conversazione
Conserva l’ID della conversazione restituito nello stato dell’interfaccia e invialo con il messaggio successivo:
const followUp = await chattybox.sendMessage({
message: 'Can you explain the second step?',
conversationId: answer.conversationId,
});
Non riutilizzare lo stesso ID tra visitatori. Ometterlo o passare null avvia una conversazione; l’ID raggruppa messaggi memorizzati. Riutilizzando lo stesso conversationId, il modello riceve fino a 12 messaggi recenti salvati, ciascuno troncato a 2.000 caratteri. È un contesto limitato, non la trascrizione completa né una memoria permanente; ripeti i dettagli più vecchi quando necessario. sendMessage() non invia sourceUrl né sourcePath; la versione dell’SDK nella sorgente attuale può inviare uiLocale, come descritto sopra.
Sicurezza dei retry
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.
Fornisci una idempotencyKey unica per ogni messaggio logico e conserva esattamente l’input originale, compreso conversationId, per un retry. L’SDK invia la chiave come header Idempotency-Key, ma non la genera né ripete la richiesta automaticamente. Le chiavi sono limitate al progetto e devono contenere 1–128 caratteri che rispettino [A-Za-z0-9][A-Za-z0-9._:-]*. Input modificati, una richiesta in corso o un errore terminale possono restituire 409. Non riprovare ogni 409 alla cieca e non generare una nuova chiave dopo un errore di trasporto ambiguo.
Il replay non è permanente: i record completati e falliti scadono normalmente 24 ore dopo la prenotazione. Una richiesta ancora in attesa non viene eseguita di nuovo in base al solo tempo: il recupero può segnarla come fallita e la pulizia di una richiesta scaduta ancora in attesa può prolungarne la scadenza. Un retry dopo la scadenza di un record terminale può essere eseguito di nuovo. Limita la finestra dei retry e indaga sui conflitti persistenti, senza presumere una deduplicazione illimitata.
Gestisci gli errori
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 contiene lo stato HTTP. code è presente solo quando l’API restituisce una stringa code; la maggior parte degli errori attuali dell’API widget non la include. Risposte non 2xx, un campo error non vuoto anche con HTTP 200, JSON non valido o JSON che non sia un oggetto generano ChattyboxError. Gli errori di rete o fetch non vengono incapsulati; l’SDK 0.1.4 incapsula invece i corpi di risposta illeggibili con il codice RESPONSE_BODY_READ_FAILED. Gli oggetti JSON riusciti vengono trattati come il tipo dichiarato senza convalida dei singoli campi a runtime.
Gli esiti comuni includono 400 per input malformati o lingue di traduzione non supportate, 401 per chiave o origine, 403 per widget disabilitato (anche nella chat headless), 409 per conflitti di idempotenza, 413 per corpi chat oltre 65.536 byte, 429 per limiti di frequenza e 500 per errori interni. L’SDK non espone gli header della risposta nel risultato o nell’errore. Se la tua interfaccia implementa retry, riusa chiave e input invariati per ogni messaggio logico; non generare una nuova chiave per una risposta persa.
Riutilizza le impostazioni del progetto e le traduzioni
L’SDK espone anche getWidgetConfig() e getWidgetTranslations(locale). Questi metodi permettono ai client di riprodurre le impostazioni del progetto e le etichette localizzate del widget ospitato:
const [config, labels] = await Promise.all([
chattybox.getWidgetConfig(),
chattybox.getWidgetTranslations('en'),
]);
La sorgente attuale dell’SDK tipizza in WidgetConfig i campi opzionali headerTitleIsDefault?: boolean e welcomeMessageIsDefault?: boolean. Ogni flag descrive il testo corrispondente: true indica un valore predefinito localizzato del prodotto, mentre false indica una stringa personalizzata da preservare. Se un flag è assente, anche nelle risposte meno recenti, la provenienza è sconosciuta; non confrontare mai il testo con un valore predefinito per dedurne la provenienza. La disponibilità dipende dal backend, non dalla versione dell’SDK. L’SDK npm pubblicato 0.1.4 non dichiara questi flag come booleani, ma il tipo Record<string, unknown> e la risposta JSON inoltrata senza modifiche consentono ai consumer di restringerne il tipo in sicurezza quando sono presenti. Le risposte riuscite non vengono validate campo per campo né sottoposte a coercizione.
Un’interfaccia completamente personalizzata può ignorarli. Conserva la conversationId di ogni visitatore nel browser o nello stato di sessione del visitatore; non condividere mai un ID di conversazione globale.
getWidgetConfig() restituisce Promise<WidgetConfig> e si autentica con Authorization: Bearer. L’SDK 0.1.4 riprova esattamente una volta con la chiave codificata nella query string solo dopo HTTP 400, per gli intermediari che rimuovono l’header; non riprova altri stati. WidgetConfig è un Record<string, unknown> con proprietà opzionali tipizzate per abilitazione, colori, posizione, titolo e benvenuto, branding, icone e impostazioni linguistiche (localeMode: 'auto' | 'fixed', defaultLocale: string, allowLocaleOverride: boolean). Verifica il tipo degli altri campi sconosciuti prima di usarli. I campi e i valori predefiniti attuali sono descritti nella personalizzazione del widget ospitato. Una richiesta di configurazione riuscita segna il widget come installato nel progetto anche se il client personalizzato non lo renderizza.
getWidgetTranslations(locale) restituisce Promise<WidgetTranslations> con translations: Record<string, string>, dir: 'ltr' | 'rtl' e la locale: string scelta dal server. L’endpoint è pubblico e non usa la chiave API o le impostazioni linguistiche del progetto. Usa uno dei codici en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy o cs. L’SDK codifica l’URL ma non normalizza la locale: fr-CA e FR restituiscono 400, a differenza della normalizzazione regionale del widget ospitato. Una stringa vuota seleziona l’inglese sul server. Tutti i cataloghi attuali sono LTR e possono essere memorizzati nella cache per un’ora.
Per un’interfaccia personalizzata, determina la locale desiderata, rispetta allowLocaleOverride e le modalità fissa/automatica del progetto se vuoi riprodurre il comportamento ospitato e prevedi fallback per le chiavi di traduzione mancanti. Queste impostazioni controllano le etichette UI; un client headless del sorgente attuale può fornire separatamente uiLocale per i fallback del prodotto, come descritto sopra. Nessuna delle due opzioni garantisce la qualità o la lingua delle risposte generate dall’AI.
Prossimi passi
- Preferisci un’interfaccia gestita senza build? Installa
widget.js. - Personalizza l’interfaccia ospitata in Personalizzazione del widget ospitato.
- Prima del lancio, prova le risposte di fallback, le citazioni e il comportamento mobile con la checklist di lancio. Se attivi restrizioni sulle origini, verifica anche le origini esatte.