Skip to main content

AI Brief: hbf-webchat

Embeddable web chat widget library built on Microsoft Bot Framework WebChat (botframework-webchat 4.18). It is bundled as a standalone JavaScript file, loaded via a script tag on any customer website, and connects to the Helvia Bot Framework via Direct Line. Supports two deployment modes (bubble floating button, embedded inline) and is extensively customisable through bot deployment configuration fetched from hbf-core at runtime.

What This Repo Does​

Exposes a global window.HBFWebchat API (init, remove, restart, getTranscript, triggerUserLeftEvent, redirectChatTo) that host pages use to mount, control, and destroy chat widget instances. On init it fetches the bot deployment configuration from hbf-core, constructs a Direct Line connection, and renders the Microsoft Bot Framework WebChat component inside a managed DOM container. Custom React components (adaptive cards, carousel, CSAT, rating form, live-chat indicators, emoji picker, speech) are injected via the webchat middleware system.

Tech Stack​

  • Language: TypeScript
  • Framework: React 18 + botframework-webchat 4.18 (Microsoft Bot Framework Direct Line)
  • Bundler: Webpack 5 (produces a single UMD JS file + CSS)
  • Key dependencies: adaptivecards 3.x, botframework-directlinespeech-sdk, microsoft-cognitiveservices-speech-sdk, emoji-picker-element, markdown-it, dompurify, deepmerge, react-select, siriwave, css-vars-ponyfill

Entry Points​

  • Public API: src/index.ts — IIFE that attaches window.HBFWebchat
  • App bootstrap: src/app.ts — selects BUBBLE or EMBEDDED widget class and injects CSS variables
  • Widget classes: src/widgets/bubbleWidget.tsx, src/widgets/embedWidget.tsx, src/widgets/coreWidget.ts
  • Webpack configs: webpack.common.js, webpack.dev.js, webpack.prod.js

Key Directories​

DirectoryPurpose
src/index.tsEntry point; IIFE; window.HBFWebchat public API
src/app.tsCSS variable injection; widget class selection (BUBBLE / EMBEDDED)
src/widgets/CoreWidget (abstract), BubbleWidget, EmbedWidget
src/components/React decorators and custom UI: AdaptiveCard, Carousel, CSAT popup, Rating Form, Live Chat, Emoji Picker, Locale Dropdown, Notifications, Back/Home/Action buttons
src/middlewares/botframework-webchat activity, attachment, card-action, and activity-status middleware factories
src/misc/WebChatConfig (deployment config fetch + merge), WebChatConfig, markdown renderer, root element manager, built-in actions, color/backward-compat utilities
src/interfaces/TypeScript interfaces: IDefaultProperties, InitConfigurations, DirectLine, enums, CSAT, rating form, etc.
src/csat/CSAT (Customer Satisfaction) survey manager
src/ratingForm/Rating form manager
src/notifications/Notification manager (startup + idle notifications)
src/preChatSteps/Pre-chat steps manager (collects user info before opening the chat)
src/history/Conversation history manager (browser storage)
src/transcript/Transcript builder for getTranscript()
src/speech/Azure Cognitive Services speech helpers (TTS / STT)
src/locale/Locale manager; i18n string lookup
src/storage/WebStorage wrapper (localStorage / sessionStorage)
src/visibilityTracker/Page visibility API tracker for idle notification timing
src/ext_libraries/Dynamic loader for botframework-webchat from CDN (deferred load)
src/assets/translations/UI strings for 25+ languages (JSON files)
src/assets/flags/Flag SVGs for locale dropdown
src/styles/SCSS stylesheets, one per component/widget

Widget Modes​

  • BUBBLE: Floating circular button in the corner. Opens/closes a chat panel. Supports auto-pop-out, user prompt bubble, pre-chat steps, pulse animation, HCN menu buttons.
  • EMBEDDED: Inline chat panel injected into a host <div>. No floating button.

External Dependencies​

  • Auth: Direct Line token fetched from tokenURL (hbf-core endpoint) on first open. Azure Speech token fetched from azureSpeechTokenURL for TTS/STT.
  • Bot config: Fetched from hbf-core public/bot-deployments/:deploymentId at init time.
  • Speech: Microsoft Cognitive Services Speech SDK (Azure) for TTS and microphone input.

Running Locally​

npm start    # webpack-dev-server with hot reload (webpack.dev.js)

Tests​

No automated tests are configured ("test": "echo \"Error: no test specified\" && exit 1").

Build​

npm run build      # production bundle (webpack.prod.js) -> dist/
npm run build:dev  # development bundle with source maps
npm run up-on-cdn  # build + deploy to CDN + clean dist