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 flottante gérée depuis une structure persistante du navigateur ou utilisez les méthodes headless avec vos propres composants. Le nettoyage complet du widget nécessite aussi le widget.js maintenu à jour ; si vous l’hébergez vous-même, mettez ce fichier à jour séparément.
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. L’option { locale: 'fr' } définit data-locale lors du montage si le projet autorise le remplacement par script ; le SDK ne fournit pas d’API réactive pour modifier cette option. Le loader du code source actuel peut néanmoins réagir aux changements ultérieurs de data-locale ou de <html lang>, comme décrit dans la section multilingue du widget ; vérifiez le comportement du loader déployé avant de vous y fier.
Les noms import.meta.env.PUBLIC_* sont des exemples : utilisez la convention publique de votre framework, comme import.meta.env.VITE_* pour Vite ou process.env.NEXT_PUBLIC_* pour Next.js. Dans Node.js, lisez et validez plutôt les valeurs de process.env.
Obtenir votre configuration publique
- Créez un projet et indexez votre contenu.
- Testez des questions représentatives dans Tester le chatbot.
- Dans Installer → Clés et domaines, examinez ou créez une clé publique et vérifiez ses origines. Une clé sans restriction fonctionne sur plusieurs origines ; une clé préparée pour un site peut déjà être restreinte. Modifier les origines permet de gérer ces restrictions facultatives.
- Dans Installer → Installation sur le site web, saisissez une URL de site web HTTP(S), choisissez une clé adaptée et copiez l’URL d’API du widget affichée avec l’extrait. Le sélecteur ne propose que les clés non expirées sans restriction ou autorisées pour l’origine de cette URL. Pour une clé restreinte, saisissez une origine autorisée ; utilisez Gérer les clés et les domaines autorisés pour examiner ses restrictions. Si le formulaire est indisponible, terminez d’abord l’étape de configuration indiquée dans le tableau de bord.
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.
Le SDK 0.1.4 exige une baseUrl HTTP(S) absolue sans identifiants, chaîne de requête ni fragment. Copiez l’URL de l’API du widget, pas l’URL du tableau de bord ni une URL Convex .cloud. Pour une clé restreinte, une origine absente ou non autorisée renvoie HTTP 401 Invalid API key ; fetch dans Node.js n’envoie pas automatiquement Origin ou Referer.
Constructeur et exports
new Chattybox(options) exige une apiKey publique et une baseUrl non vides. L’option fetch accepte une implémentation compatible ; sinon le client utilise fetch global. Le SDK retire les barres obliques finales puis le suffixe /chat final de l’URL. Les propriétés apiKey et baseUrl normalisée sont accessibles en lecture seule. Des options absentes ou invalides, une clé ou URL vide ou non textuelle, un fetch fourni qui n’est pas une fonction ou une URL invalide provoquent une Error ordinaire.
Le package exporte Chattybox, ChattyboxError et les types ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions et HostedWidgetHandle. Il ne fournit ni composant React ni hooks. Le bundle IIFE ./browser expose les deux constructeurs sur window.ChattyboxSDK ; son chargement seul ne monte aucune interface.
Monter le widget hébergé depuis le code
Utilisez cette méthode pour initialiser l’interface flottante gérée de ChattyBox depuis le code de l’application :
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 : appelez remove() sur chacun. Le dernier handle signale le démontage et retire le script ; avec le widget hébergé widget.js v15, ce signal annule aussi l’initialisation, les nouvelles tentatives et le chat en cours, puis retire l’UI et ses ressources. Le nettoyage ne peut pas annuler une requête déjà traitée par le serveur. 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 du widget. Le SDK ne fournit ni promesse ready, ni cible de conteneur, ni API réactive de mise à jour de locale ; n’associez pas SDK, plugin, GTM et script manuel sur la même page.
L’option scriptUrl vaut par défaut https://chattybox.ai/widget.js ; ne la remplacez que par un loader de prévisualisation fiable ou auto-hébergé. locale définit data-locale si elle est non vide ; le projet doit autoriser ce remplacement pour qu’il soit pris en compte. debug active data-debug="true" lorsqu’il est vrai ; les diagnostics sont désactivés par défaut. handle.element est la balise script injectée ou réutilisée. Le SDK ne détecte pas les chargeurs manuels sans attribut marqueur, et le fetch personnalisé du constructeur ne s’applique qu’aux méthodes headless, pas au widget hébergé.
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 Installer → Installation sur le site web. Le SDK accepte la racine du déploiement ou une URL se terminant par /chat.
La réponse contient :
| Champ | Type | Description |
|---|---|---|
message | string | Réponse ou message de repli configuré ; affichez-le en texte ou en Markdown assaini, pas en HTML brut. |
conversationId | string | Identifiant utilisé pour poursuivre cette conversation. |
sources | string[] | URL des sources ; peut être vide pour un repli. Validez les URL HTTP(S) avant de créer des liens. |
providerError | string (facultatif, source actuelle) | Code structuré d’échec du fournisseur. Absent pour les réponses ordinaires et les messages de repli configurés ; traitez les codes inconnus comme une erreur générique. |
productFallback | 'no_context_ui' | 'no_context_question' (facultatif, backend actuel) | Indique un message de repli sans contexte appartenant au produit et la façon dont sa langue a été choisie ; voir ci-dessous. |
sendMessage(input) renvoie Promise<ChatResponse>. SendMessageInput accepte message: string, conversationId: string | null facultatif et idempotencyKey: string facultatif. Le code source actuel accepte aussi uiLocale: string facultatif ; cette option n’est pas disponible dans le SDK publié 0.1.4. Le SDK envoie la clé publique dans le corps JSON. Il n’envoie ni contexte de page (sourceUrl ou sourcePath), ni options de modèle. Validez un message non vide d’au plus 2 000 caractères après suppression des espaces aux extrémités avant l’envoi ; le backend applique cette limite, mais ses erreurs de validation internes apparaissent actuellement comme des erreurs HTTP 500 génériques.
Par exemple, avec le SDK et le backend du code source actuel, utilisez chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). Le SDK transmet la locale fournie sans la modifier et l’omet si elle est absente ou vaut undefined ; il ne détecte pas automatiquement la locale. Le serveur la valide et la normalise vers une langue de base prise en charge. Les valeurs mal formées ou non prises en charge renvoient HTTP 400 Invalid uiLocale au lieu d’être silencieusement remplacées. La locale est un contexte de présentation fourni par l’appelant, pas un contrôle d’authentification ou d’autorisation.
Un signal reconnu sur la langue de la question prime sur uiLocale pour les messages de repli appartenant au produit. Si la détection n’est pas concluante ou repose uniquement sur l’heuristique d’anglais ASCII, la locale de l’interface peut déterminer leur langue ; en l’absence de ces deux signaux, les valeurs de repli du produit s’appliquent. Un message de repli rédigé par le projet est utilisé tel quel à la place du message de repli du produit en l’absence de contexte. La locale de l’interface ne traduit ni ce texte rédigé par le projet ni le contenu généré par l’IA, et ne garantit ni la qualité ni la langue de la réponse.
L’API widget/chat du backend actuel n’ajoute productFallback qu’aux réponses de repli sans contexte appartenant au produit ; sa présence dépend de la version du backend, pas de celle du SDK. no_context_ui signifie que la langue du message de repli a été choisie à partir de la locale de l’interface ou de la locale par défaut, ou qu’elle n’a pas pu être déterminée ; une interface personnalisée peut le relocaliser à l’aide de l’entrée actuelle du catalogue message.noContext. no_context_question signifie que le classificateur a reconnu la langue de la question ; conservez le texte renvoyé. Le classificateur peut se tromper : ce marqueur ne garantit pas que la langue a été correctement identifiée. Le marqueur est absent pour les messages de repli personnalisés, les réponses ordinaires, les échecs du fournisseur et les réponses d’anciennes versions. N’inférez jamais l’origine du message à partir de son texte (même s’il correspond exactement à un texte connu) ni de l’absence du marqueur ; ignorez les valeurs de marqueur inconnues.
Le SDK publié 0.1.4 ne déclare pas productFallback dans ChatResponse, mais transmet ce champ dans l’objet JSON renvoyé si le backend le fournit. Vérifiez et réduisez la valeur de façon sûre avant de l’utiliser. Il n’existe pas de champ général wasAnswered ni de statut de repli ; n’inventez pas de résultat structuré signalant qu’une réponse n’est pas prise en charge.
sendMessage() ne fournit ni streaming, ni nouvelles tentatives automatiques, ni délai maximal, ni option AbortSignal, ni stockage ou état d’interface. Un fetch personnalisé peut définir une politique de transport. Cette absence de nouvelle tentative concerne le chat headless : le SDK 0.1.4 ne réessaie getWidgetConfig() qu’une fois après HTTP 400, et le widget hébergé v15 réessaie séparément ses requêtes GET de démarrage.
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 ; réutiliser le même conversationId fournit au modèle jusqu’à 12 messages récents enregistrés, chacun tronqué à 2 000 caractères. Ce contexte est limité, pas l’intégralité de la conversation ni une mémoire permanente ; rappelez les détails plus anciens si nécessaire.
Passer null démarre également une nouvelle conversation.
Sécurité des nouvelles tentatives
const input = {
message: 'Where is the API reference?',
idempotencyKey: crypto.randomUUID(),
};
const result = await chattybox.sendMessage(input);
// If the response is lost, retry the same input, including its original conversationId.
Fournissez une idempotencyKey unique par message logique et conservez exactement la même entrée pour une nouvelle tentative, y compris le conversationId initial et uiLocale ou son omission. Le SDK envoie la clé dans Idempotency-Key, mais ne la crée pas et ne réessaie pas à votre place. Les clés sont propres au projet ; elles doivent comporter entre 1 et 128 caractères et respecter [A-Za-z0-9][A-Za-z0-9._:-]*. Une requête identique déjà terminée peut être rejouée avec son message et son éventuel marqueur d’origine sans être exécutée à nouveau. Une entrée modifiée, une requête en cours ou un échec définitif peuvent renvoyer 409. Le serveur actuel inclut la locale normalisée dans l’empreinte de la requête ; ne réessayez pas aveuglément chaque 409 et ne générez pas de nouvelle clé après un échec de transport ambigu.
Les enregistrements d’idempotence terminés ou échoués expirent 24 heures après leur réservation ; après expiration, une nouvelle tentative peut être exécutée à nouveau. Les enregistrements en attente ne sont pas récupérés par le seul passage du temps : limitez la durée des tentatives et examinez les conflits persistants.
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 ; pour les erreurs renvoyées par l’API, code n’est présent que si celle-ci renvoie une chaîne code, ce que la plupart des erreurs actuelles ne font pas. Une réponse non 2xx, un champ error textuel non vide même en HTTP 200, un JSON invalide ou un JSON qui n’est pas un objet déclenchent ChattyboxError. Les erreurs réseau ou de fetch ne sont pas enveloppées. Le SDK 0.1.4 enveloppe aussi les corps de réponse illisibles avec le code RESPONSE_BODY_READ_FAILED. Les objets JSON réussis sont convertis vers le type déclaré sans validation de chaque champ à l’exécution.
Les statuts courants comprennent 400 pour une entrée mal formée ou une locale de traduction non prise en charge, 401 pour une clé ou origine invalide, 403 pour un widget désactivé (y compris le chat headless), 409 pour un conflit d’idempotence, 413 pour un corps de chat supérieur à 65 536 octets, 429 pour une limitation de débit et 500 pour une erreur interne. Le SDK n’expose pas les en-têtes de réponse dans son résultat ou son erreur.
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.
getWidgetConfig() renvoie Promise<WidgetConfig> et utilise Authorization: Bearer. Le SDK 0.1.4 ne réessaie qu’une fois avec la clé encodée dans la chaîne de requête, uniquement après HTTP 400, pour les intermédiaires qui retirent l’en-tête. WidgetConfig est un Record<string, unknown> avec des propriétés typées facultatives pour l’activation, les couleurs, la position, le titre et le message d’accueil, la marque, les icônes et les réglages de locale. Vérifiez le type des autres champs avant de les utiliser. Les champs et valeurs par défaut du serveur actuel figurent dans Personnaliser le widget hébergé. Une requête de configuration réussie marque aussi le widget du projet comme installé, même si votre client personnalisé ne l’affiche jamais.
Le code source actuel du SDK ajoute à WidgetConfig les propriétés headerTitleIsDefault?: boolean et welcomeMessageIsDefault?: boolean. Chaque indicateur décrit le texte correspondant : true signifie qu’il s’agit d’une valeur par défaut du produit localisée, tandis que false indique un texte personnalisé à conserver. Si un indicateur est absent, y compris dans les anciennes réponses, sa provenance est inconnue ; ne comparez jamais le texte à une valeur par défaut pour la déduire. La disponibilité dépend de la version du backend, pas de celle du SDK. Le SDK publié 0.1.4 ne déclare pas ces indicateurs comme booléens, mais son type Record<string, unknown> et la transmission inchangée de la réponse JSON permettent aux consommateurs d’en vérifier le type en toute sécurité lorsqu’ils sont présents. Les réponses réussies ne font l’objet d’aucune validation champ par champ ni coercition.
getWidgetTranslations(locale) renvoie Promise<WidgetTranslations> avec translations: Record<string, string>, dir: 'ltr' | 'rtl' et la locale choisie par le serveur. Ce point de terminaison public n’utilise ni clé API ni réglages de langue du projet. Les codes pris en charge sont en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy et cs. Le SDK encode l’URL mais ne normalise pas la locale : fr-CA et FR renvoient 400, contrairement à la normalisation du loader hébergé. Une chaîne vide sélectionne l’anglais côté serveur. Les catalogues actuels sont tous de gauche à droite et peuvent être mis en cache pendant une heure.
Pour reproduire le comportement hébergé, choisissez la locale dans votre interface, respectez allowLocaleOverride et les modes fixed/auto, et prévoyez un repli pour les clés de traduction manquantes. Ces réglages concernent les libellés de l’interface ; un client headless du code source actuel peut fournir séparément uiLocale pour les messages de repli du produit. La locale ne traduit pas la demande ni le contenu indexé et ne garantit ni la qualité ni la langue de la réponse générée.
É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 réponses de repli, les citations et le comportement mobile avec la checklist de lancement ; testez également les origines exactes si vous activez une restriction.