Passa al contenuto principale
ChattyBox Logo

SDK JavaScript

L'SDK JavaScript è il percorso consigliato per le nuove integrazioni guidate dagli sviluppatori. Crea la tua esperienza di chat mentre ChattyBox gestisce recupero, citazioni, conversazioni e scalabilità. Se vuoi un'interfaccia pronta all'uso senza aggiungere codice all'applicazione, utilizza invece il widget ospitato, che dispone di supporto completo.

Prima di iniziare​

  1. Crea un progetto e indicizza i contenuti.
  2. Prova domande rappresentative nella dashboard.
  3. Apri la scheda Incorpora del progetto.
  4. Crea o seleziona una chiave API pubblica del widget e configurane le origini consentite.
  5. Copia l'URL API del widget mostrato insieme allo snippet di incorporamento.

Le chiavi API pubbliche del widget sono progettate per essere incluse nel codice del browser. Identificano un progetto, ma non sono credenziali di amministrazione. Limita le chiavi del browser ai domini che devono essere autorizzati a chiamare il chatbot.

Installazione​

bun add @openstaticfish/chattybox

Il pacchetto è un client ESM per le applicazioni Node.js e browser attuali che forniscono fetch.

Inviare 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 riportato nella scheda Incorpora. L'SDK accetta sia la radice del deployment sia un URL che termina con /chat.

La risposta contiene:

CampoTipoDescrizione
messagestringLa risposta generata.
conversationIdstringL'identificatore usato per continuare la conversazione.
sourcesstring[]Gli URL delle fonti recuperate per la risposta.

Continuare una conversazione​

Conserva l'ID 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 conversazione per visitatori distinti e non correlati. Crea una nuova conversazione omettendo conversationId dal loro primo messaggio.

Gestire 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.

Compatibilità avanzata con il widget​

L'SDK espone anche getWidgetConfig() e getWidgetTranslations(locale). Questi metodi supportano i client che vogliono riprodurre le impostazioni del progetto e le etichette localizzate del widget ospitato. Un'interfaccia completamente personalizzata può ignorarli.

Passaggi successivi​