Passer au contenu principal
ChattyBox Logo

SDK JavaScript

Le SDK JavaScript est la solution recommandée pour les nouvelles intégrations pilotées par des développeurs. Créez votre propre expérience de chat pendant que ChattyBox gère la recherche, les citations, les conversations et la mise à l'échelle. Si vous souhaitez une interface prête à l'emploi sans code applicatif, utilisez plutôt le widget hébergé, entièrement pris en charge.

Avant de commencer​

  1. Créez un projet et indexez votre contenu.
  2. Testez des questions représentatives dans le tableau de bord.
  3. Ouvrez l'onglet Embed du projet.
  4. Créez ou sélectionnez une clé API publique de widget et configurez ses origines autorisées.
  5. Copiez l'URL API du widget affichée avec l'extrait d'intégration.

Les clés API publiques de widget sont conçues pour apparaître dans le code exécuté par le navigateur. Elles identifient un projet, mais ne constituent pas des identifiants de gestion. Limitez les clés de navigateur aux domaines autorisés à appeler votre chatbot.

Installation​

bun add @openstaticfish/chattybox

Le package est un client ESM destiné aux applications Node.js actuelles et aux applications de navigateur qui fournissent fetch.

Envoyer un message​

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

Définissez PUBLIC_CHATTYBOX_API_URL sur l'URL API exacte du widget indiquée dans l'onglet Embed. Le SDK accepte aussi bien la racine du déploiement qu'une URL se terminant par /chat.

La réponse contient :

ChampTypeDescription
messagestringLa réponse générée.
conversationIdstringL'identifiant utilisé pour poursuivre cette conversation.
sourcesstring[]Les URL des sources utilisées pour générer la réponse.

Poursuivre une conversation​

Conservez l'identifiant de conversation renvoyé dans l'état de votre interface et envoyez-le avec le message suivant :

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

Ne réutilisez pas le même identifiant de conversation pour des visiteurs sans lien entre eux. Créez une nouvelle conversation en omettant conversationId lors de leur premier message.

Gérer les erreurs​

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 contient le statut HTTP. code est présent lorsque l'API renvoie un code d'erreur structuré.

Compatibilité avancée avec le widget​

Le SDK expose également getWidgetConfig() et getWidgetTranslations(locale). Ces méthodes s'adressent aux clients qui souhaitent reproduire les paramètres du projet et les libellés localisés du widget hébergé. Une interface entièrement personnalisée peut les ignorer.

Étapes suivantes​