SDK JavaScript

:::note État des versions Le SDK npm publié 0.1.4 valide baseUrl, enveloppe les corps de réponse illisibles et ne réessaie config HTTP 400 qu’une fois. Avec widget.js v15, remove()/window.ChattyBox.destroy() permet le teardown ; sendMessage() headless ne réessaie pas automatiquement. :::

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

// Conservez ce loader pendant toute la durée de la page.

Appelez mountWidget() après l’existence de document.body, dans le navigateur et depuis un shell persistant. Il ajoute un widget flottant sous document.body, pas dans votre composant. { locale: 'fr' } ne demande cette langue qu’à l’initialisation et seulement si le projet autorise le remplacement par script.

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 et créez une clé navigateur. Elle fonctionne par défaut en production, prévisualisation, staging et localhost ; activez facultativement Edit origins pour limiter des origines exactes.
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 publiques sont prévues pour le navigateur : elles identifient un projet, pas un droit de gestion. Une restriction facultative compare exactement schéma, hôte et port (pas les chemins ni les sous-domaines génériques) à Origin, ou à l’origine de Referer. Elle n’est pas une authentification et un client non navigateur peut forger ces en-têtes. Le package est un client ESM pour Node.js et les navigateurs 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({ locale: 'fr', debug: false });

mountWidget() renvoie immédiatement un handle, avant le chargement de l’UI. Dans le SDK publié 0.1.4, des montages identiques partagent le script et chaque handle détient une référence : remove() est idempotent et seul le dernier handle annule l’initialisation, les nouvelles tentatives et le chat en cours, puis retire l’UI, les styles, les liens de polices, le script et l’API globale. Une clé, URL, scriptUrl, locale ou option debug différente est refusée tant que des handles existent. Avec widget.js v15, window.ChattyBox.destroy() effectue le même teardown. Il n’existe ni promesse ready, ni cible de conteneur, ni mise à jour réactive de locale ; n’associez pas SDK, plugin, GTM et script manuel sur la même page.

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.

sendMessage() accepte seulement message, conversationId optionnel et idempotencyKey optionnel. Il n’envoie pas sourceUrl, sourcePath, locale ni options de modèle. Validez un message non vide d’au plus 2 000 caractères ; le SDK n’offre ni streaming, délai, AbortSignal ni nouvelles tentatives automatiques.

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. L’identifiant regroupe les messages stockés, mais les tours précédents ne sont pas actuellement transmis au modèle : rendez chaque suivi autonome.

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 n’est présent que si l’API en renvoie un. Les erreurs réseau ne sont pas enveloppées. Les réponses de repli peuvent avoir sources vide ; il n’existe pas de statut public séparé « répondu ». Utilisez une clé d’idempotence unique par message logique et réessayez exactement la même entrée, sans réessayer aveuglément chaque 409.

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.

Pour reproduire le comportement hébergé, respectez allowLocaleOverride et les modes fixed/auto. La locale ne traduit pas la demande ni le contenu indexé et ne garantit pas la qualité de la réponse. getWidgetTranslations() accepte les codes de catalogue, mais ne normalise pas fr-CA ou FR comme le loader hébergé.

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