SDK Chatbot JavaScript et TypeScript (npm)

SDK JavaScript

Le paquet webchatagent est le client JavaScript et TypeScript officiel pour l'API REST et l'API WebSocket. Utilisez-le lorsque le Widget prêt à l'emploi ne convient pas et que vous souhaitez votre propre interface de chat : votre propre design, une application React ou Vue, un conteneur natif ou une intégration côté serveur. Il communique avec le même Chatbot, avec les mêmes connaissances, outils et paramètres que le Widget.

• Fonctions typées pour tout ce que fait le Widget : réponses, streaming, suggestions de relance, sources, téléchargement de fichiers, retours utilisateurs, formulaires de prospects, transfert à un humain et Chat en direct
• Aucune dépendance, types TypeScript stricts, fonctionne dans les navigateurs, Node.js 22.12+, Bun et Deno
• Open source sous licence MIT : github.com/WebChatAgent/webchatagent-js

Installation

npm install webchatagent

Vous avez besoin de votre Identifiant du chatbot : dans le Tableau de bord, ouvrez votre Chatbot, puis Actions du chatbot → Copier l’identifiant du chatbot.

Premier message

import { WebChatAgent } from 'webchatagent'

const chat = new WebChatAgent({ chatbotId: 'YOUR-CHATBOT-ID', storage: localStorage })

const reply = await chat.send('What are your opening hours?')
console.log(reply.text) // the answer as Markdown

storage: localStorage conserve la conversation d'un chargement de page à l'autre. Chaque appel ultérieur à send() poursuit la même conversation.

Dans le navigateur, l'API répond uniquement aux pages figurant dans les Sites autorisés de votre Chatbot, si vous en avez configuré. localhost fonctionne toujours pour le développement.

Réponses en streaming

for await (const event of chat.stream('Which plan fits a small shop?')) {
  if (event.type === 'text') bubble.innerHTML = render(event.text) // full answer so far
  if (event.type === 'done') showSuggestions(event.reply.suggestions)
}

event.text est déjà nettoyé, de sorte que les liens incomplets ou les problèmes de mise en forme n'apparaissent jamais. Les réponses sont en Markdown : affichez-les avec une bibliothèque Markdown et nettoyez le HTML (par exemple avec DOMPurify).

Ce que couvre le SDK

getConfig().features vous indique lesquelles de ces options sont disponibles pour le Chatbot, afin que votre interface n'affiche que ce qui fonctionne.

Transfert à un humain

Lorsque le bot passe le relais à votre équipe, ou que le visiteur demande à parler à une personne, la réponse revient avec mode: 'human'. Ouvrez le Chat en direct et les messages du membre de l'équipe arrivent en temps réel :

if (reply.mode === 'human') {
  const live = chat.liveChat()
  live.on('message', (message) => showMessage(message))
  live.on('ended', () => backToBot())
  await live.send('Hello, I need help with order 1234.')
}

Votre équipe répond dans le Tableau de bord sous Chat en direct, exactement comme avec le Widget.

Ce que vous devez afficher

Avec votre propre interface, trois éléments que le Widget gère automatiquement sont à votre charge :

1. Mention de marque : si config.branding.required vaut true, affichez config.branding.text avec un lien vers config.branding.url.
2. Indication IA : signalez les réponses avec aiGenerated: true comme étant générées par l'IA.
3. Avis de confidentialité : affichez config.widget.privacyPolicyHtml.

Référence complète

Le fichier README sur GitHub contient la référence complète de l'API, les codes d'erreur, les limites, des exemples pour React, Vue/Nuxt, JavaScript pur et Node.js, ainsi qu'une section pour les assistants de programmation IA comme Claude Code, Cursor ou Copilot. Une page de chat complète sans framework est disponible dans examples/browser.html.