JavaScript & TypeScript Chatbot SDK (npm)

JavaScript SDK

The webchatagent package is the official JavaScript and TypeScript client for the REST API and the WebSocket API. Use it when the ready-made widget does not fit and you want your own chat interface: your own design, a React or Vue app, a native shell or a server-side integration. It talks to the same chatbot, with the same knowledge, tools and settings as the widget.

Typed functions for everything the widget does: answers, streaming, suggested follow-ups, sources, file upload, feedback, lead forms, human handover and live chat
No dependencies, strict TypeScript types, runs in browsers, Node.js 22.12+, Bun and Deno
Open source under the MIT license: github.com/WebChatAgent/webchatagent-js

Install

npm install webchatagent

You need your Chatbot ID: in the dashboard open your chatbot, then Chatbot actions → Copy chatbot ID.

First 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 keeps the conversation across page loads. Every further send() continues the same conversation.

In the browser, the API answers only pages on your chatbot's Allowed websites, if you set any. localhost always works for development.

Streaming answers

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 is already cleaned, so half-written links or formatting never show up. Answers are Markdown: render them with a Markdown library and sanitize the HTML (for example with DOMPurify).

What the SDK covers

Feature	Method	Needs
Send a message	`send()` / `stream()`
Restore a conversation	`history()`
Title, welcome message, starter questions, colors	`getConfig()`
Let visitors send files to the bot	`upload()` + `send(text, { attachment })`	File upload switched on, Premium or higher
Thumbs up/down on answers	`feedback()`	Feedback function switched on
Lead forms from the Action Bar	`submitForm()`	Form active in the Action Bar
Ask for a person	`requestHuman()`	Live chat switched on
Chat with your team in real time	`liveChat()`	Live chat switched on

getConfig().features tells you which of these are available for the chatbot, so your UI only shows what works.

Human handover

When the bot hands the conversation to your team, or the visitor asks for a person, the reply comes back with mode: 'human'. Open the live chat and the team member's messages arrive in real time:

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

Your team answers in the dashboard under Live chat, exactly as with the widget.

What you need to show

With your own interface, three things the widget does automatically are your job:

"Powered by" notice: if config.branding.required is true, show config.branding.text linked to config.branding.url.
AI label: mark answers with aiGenerated: true as AI-generated.
Privacy notice: show config.widget.privacyPolicyHtml.

Full reference

The README on GitHub has the complete API reference, error codes, limits, recipes for React, Vue/Nuxt, vanilla JavaScript and Node.js, and a section for AI coding assistants such as Claude Code, Cursor or Copilot. A complete chat page without a framework is in examples/browser.html.