JavaScript & TypeScript Chatbot SDK (npm)

JavaScript SDK

Das Paket webchatagent ist der offizielle JavaScript- und TypeScript-Client für die REST API und die WebSocket API. Nutzen Sie es, wenn das vorgefertigte Widget nicht passt und Sie eine eigene Chat-Oberfläche möchten: Ihr eigenes Design, eine React- oder Vue-App, ein natives Anwendungsfenster oder eine serverseitige Integration. Es kommuniziert mit demselben Chatbot, mit demselben Wissen, denselben Werkzeugen und denselben Einstellungen wie das Widget.

• Typisierte Funktionen für alles, was das Widget kann: Antworten, Streaming, vorgeschlagene Folgefragen, Quellen, Datei-Upload, Feedback, Lead-Formulare, Übergabe an Menschen und Live-Chat
• Keine Abhängigkeiten, strikte TypeScript-Typen, läuft im Browser, in Node.js 22.12+, Bun und Deno
• Open Source unter der MIT-Lizenz: github.com/WebChatAgent/webchatagent-js

Installation

npm install webchatagent

Sie benötigen Ihre Chatbot-ID: Öffnen Sie im Dashboard Ihren Chatbot und wählen Sie dann Chatbot-Aktionen → Chatbot-ID kopieren.

Erste Nachricht

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 behält die Unterhaltung über Seitenaufrufe hinweg bei. Jedes weitere send() setzt dieselbe Unterhaltung fort.

Im Browser antwortet die API nur Seiten auf den Erlaubte Websites Ihres Chatbots, sofern Sie welche eingerichtet haben. localhost funktioniert für die Entwicklung immer.

Antworten streamen

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 ist bereits bereinigt, sodass unvollständige Links oder Formatierungen gar nicht erst sichtbar werden. Antworten sind Markdown: Rendern Sie sie mit einer Markdown-Bibliothek und bereinigen Sie das HTML (zum Beispiel mit DOMPurify).

Was das SDK abdeckt

getConfig().features zeigt Ihnen, welche dieser Funktionen für den Chatbot verfügbar sind, damit Ihre UI nur anzeigt, was funktioniert.

Übergabe an Menschen

Wenn der Bot die Unterhaltung an Ihr Team übergibt oder der Besucher nach einer Person fragt, enthält die Antwort mode: 'human'. Öffnen Sie den Live-Chat, damit die Nachrichten des Teammitglieds in Echtzeit ankommen:

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.')
}

Ihr Team antwortet im Dashboard unter Live-Chat, genau wie beim Widget.

Was Sie anzeigen müssen

Bei einer eigenen Oberfläche liegen drei Dinge, die das Widget automatisch erledigt, in Ihrer Verantwortung:

1. "Powered by"-Hinweis: Wenn config.branding.required den Wert true hat, zeigen Sie config.branding.text verlinkt auf config.branding.url an.
2. KI-Kennzeichnung: Markieren Sie Antworten mit aiGenerated: true als KI-generiert.
3. Datenschutzhinweis: Zeigen Sie config.widget.privacyPolicyHtml an.

Vollständige Referenz

Die README auf GitHub enthält die komplette API-Referenz, Fehlercodes, Limits, Vorlagen für React, Vue/Nuxt, reines JavaScript und Node.js sowie einen Abschnitt für KI-Coding-Assistenten wie Claude Code, Cursor oder Copilot. Eine vollständige Chat-Seite ohne Framework finden Sie in examples/browser.html.