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. Importa un client nella tua applicazione, configura la chiave pubblica e l’URL API, poi monta l’interfaccia gestita dove serve oppure usa i metodi headless con i tuoi componenti.

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 codice del browser dal componente o dal layout in cui deve essere disponibile l’interfaccia gestita. Puoi passare { locale: 'fr' } per una route con una lingua specifica.

Ottieni la configurazione pubblica

1. Crea un progetto e indicizza i contenuti.
2. Prova domande rappresentative nella dashboard.
3. Apri Public Keys, crea una chiave per il browser e limita le origini consentite.
4. Apri Embed, seleziona la chiave e copia l’URL API del widget mostrato insieme allo snippet generato.

Le chiavi API pubbliche del widget sono pensate per comparire nel codice del browser. Identificano un progetto, ma non sono credenziali di gestione. Limita le chiavi del browser ai domini che devono poter chiamare il chatbot. Il pacchetto è un client ESM per applicazioni Node.js e browser moderni che forniscono fetch.

Monta il widget ospitato dal codice

Usa questa soluzione quando vuoi l’interfaccia gestita di ChattyBox, controllando però dal codice dell’applicazione dove montarla:

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 solo l’ultimo handle annulla inizializzazione, retry e chat in corso, quindi rimuove UI, stili, link ai font, script e API globale. Una chiave, URL API, scriptUrl, locale o opzione debug diversa viene rifiutata finché esistono handle. Con widget.js v15, window.ChattyBox.destroy() esegue lo stesso teardown. Non esistono promise ready, contenitore o aggiornamento reattivo del locale; scegli un solo loader.

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 nella scheda Embed. L’SDK accetta la radice del deployment oppure un URL che termina con /chat.

La risposta contiene:

Campo	Tipo	Descrizione
message	string	La risposta generata.
conversationId	string	Identificatore usato per continuare questa conversazione.
sources	string[]	URL delle fonti recuperate per la risposta.

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, ma i turni precedenti non vengono passati al modello. sendMessage() accetta solo message, conversationId e idempotencyKey, non sourceUrl.

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 quando l’API restituisce un codice di errore strutturato.

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'),
]);

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.

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 restrizioni sull’origine, le risposte di fallback, le citazioni e il comportamento mobile con la checklist di lancio.