SDK JavaScript

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

// Call this from your component's cleanup lifecycle when appropriate.
// widget.remove();

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

// Optional cleanup for a component lifecycle:
widget.remove();

Carica l’interfaccia gestita una sola volta e non è disponibile durante il rendering lato server.

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 di conversazione per visitatori non correlati. Crea una nuova conversazione omettendo conversationId per il loro primo messaggio.

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.