JavaScript и TypeScript Chatbot SDK (npm)

JavaScript SDK

Пакет webchatagent представляет собой официальный клиент JavaScript и TypeScript для REST API и WebSocket API. Используйте его, когда готовый виджет не подходит и вам нужен собственный интерфейс чата: собственный дизайн, приложение на React или Vue, нативная оболочка или серверная интеграция. Он обращается к тому же чат-боту, с теми же знаниями, инструментами и настройками, что и виджет.

• Типизированные функции для всех возможностей виджета: ответы, потоковая передача, варианты продолжения диалога, источники, загрузка файлов, обратная связь, лид-формы, перевод на оператора и живой чат
• Без зависимостей, со строгой типизацией TypeScript, работает в браузерах, Node.js 22.12+, Bun и Deno
• Открытый исходный код под лицензией MIT: github.com/WebChatAgent/webchatagent-js

Установка

npm install webchatagent

Вам потребуется ID чат-бота: в панели управления откройте вашего чат-бота, затем выберите Действия с чат-ботом → Копировать ID чат-бота.

Первое сообщение

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 сохраняет диалог между перезагрузками страницы. Каждый последующий вызов send() продолжает тот же диалог.

В браузере API отвечает только страницам из списка Разрешённые сайты вашего чат-бота, если вы их настроили. Для разработки localhost доступен всегда.

Потоковая передача ответов

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 уже очищено, поэтому недописанные ссылки или фрагменты разметки не отобразятся. Ответы приходят в формате Markdown: отображайте их с помощью библиотеки Markdown и очищайте полученный HTML (например, через DOMPurify).

Возможности SDK

Свойство getConfig().features показывает, какие из этих функций доступны для чат-бота, позволяя отображать в интерфейсе только рабочие элементы.

Перевод на оператора

Когда бот переводит диалог на команду или посетитель сам просит позвать человека, в ответе возвращается mode: 'human'. Откройте живой чат, и сообщения от оператора будут поступать в реальном времени:

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

Ваша команда отвечает в панели управления в разделе Живой чат, точно так же, как при работе через виджет.

Обязательные требования к отображению

При создании собственного интерфейса три вещи, которые виджет делает автоматически, переходят на вашу сторону:

1. Уведомление "Powered by": если config.branding.required имеет значение true, покажите текст config.branding.text со ссылкой на config.branding.url.
2. Отметка об ИИ: помечайте ответы с флагом aiGenerated: true как сгенерированные ИИ.
3. Уведомление о конфиденциальности: покажите config.widget.privacyPolicyHtml.

Полная документация

В файле README на GitHub доступен полный справочник по API, коды ошибок, лимиты, примеры интеграции для React, Vue/Nuxt, чистого JavaScript и Node.js, а также раздел для ИИ-ассистентов разработки, таких как Claude Code, Cursor или Copilot. Полноценная страница чата без фреймворков находится в examples/browser.html.