SDK JavaScript

Le package npm est la méthode recommandée pour intégrer ChattyBox. Importez un client dans votre application, configurez votre clé publique et votre URL d’API, puis montez l’interface gérée là où votre application en a besoin ou utilisez les méthodes headless avec vos propres composants.

Démarrage rapide

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

Appelez mountWidget() dans le code exécuté dans le navigateur, depuis le composant ou le layout où l’interface gérée doit être disponible. Vous pouvez transmettre { locale: 'fr' } pour une route avec une langue spécifique.

Obtenir votre configuration publique

1. Créez un projet et indexez votre contenu.
2. Testez des questions représentatives dans le tableau de bord.
3. Ouvrez Public Keys, créez une clé navigateur et limitez ses origines autorisées.
4. Ouvrez Embed, sélectionnez cette clé et copiez l’URL d’API du widget affichée avec l’extrait généré.

Les clés d’API publiques du widget sont destinées à apparaître dans le code du navigateur. Elles identifient un projet, mais ne constituent pas des identifiants de gestion. Limitez les clés navigateur aux domaines autorisés à appeler votre chatbot. Le package est un client ESM pour les applications Node.js et navigateur actuelles qui fournissent fetch.

Monter le widget hébergé depuis le code

Utilisez cette méthode si vous souhaitez l’interface gérée de ChattyBox tout en contrôlant depuis le code de l’application l’endroit où elle est montée :

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

L’interface gérée est chargée une seule fois et n’est pas disponible pendant le rendu côté serveur.

Créer votre propre interface

Utilisez les méthodes headless ci-dessous lorsque votre application gère elle-même la liste des messages, la saisie, les états de chargement et d’erreur, les citations et l’accessibilité.

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 exacte de l’API du widget indiquée dans l’onglet Embed. Le SDK accepte la racine du déploiement ou une URL se terminant par /chat.

La réponse contient :

Champ	Type	Description
message	string	La réponse générée.
conversationId	string	Identifiant utilisé pour poursuivre cette conversation.
sources	string[]	URL des sources récupérées pour 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 un même identifiant de conversation pour des visiteurs sans lien entre eux. Créez une nouvelle conversation en omettant conversationId pour 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é.

Réutiliser les paramètres du projet et les traductions

Le SDK expose également getWidgetConfig() et getWidgetTranslations(locale). Ces méthodes permettent aux clients de reproduire les paramètres du projet et les libellés localisés du widget hébergé :

const [config, labels] = await Promise.all([
  chattybox.getWidgetConfig(),
  chattybox.getWidgetTranslations('en'),
]);

Une interface entièrement personnalisée peut les ignorer. Conservez la conversationId de chaque visiteur dans le navigateur ou l’état de session de ce visiteur ; ne partagez jamais un identifiant de conversation global.

Étapes suivantes

• Vous préférez une interface gérée sans build ? Installez widget.js.
• Personnalisez l’interface hébergée dans Personnaliser le widget hébergé.
• Avant le lancement, testez les restrictions d’origine, les réponses de repli, les citations et le comportement mobile avec la checklist de lancement.