BotFramework-WebChat: Microsoft's customizable chat UI component for Bot Framework bots

The Bot Framework SDK and Web Chat are separate repositories; only the SDK was archived on GitHub

BotFramework-WebChat is a highly-customizable web-based client for the Bot Framework SDK, part of Microsoft's framework for building enterprise-grade conversational AI experiences according to the README.

The Bot Framework SDK was archived on GitHub in December 2025, but Web Chat is a separate repository and is not archived. That separation matters when evaluating the library for long-term adoption: the SDK's move to archival status does not retire Web Chat, but both projects share the same parent ecosystem, and any bot that depends on SDK-level features is worth checking against the SDK's current situation. Web Chat connects to bots through DirectLine, a protocol and library with its own repository, and changes to the broader SDK can still affect production behavior even though Web Chat's own code remains active.

Installing from NPM as botframework-webchat; the semver strategy the README recommends

Web Chat ships on NPM under the name botframework-webchat. For the Fluent UI theme pack, a second package, botframework-webchat-fluent-theme, ships separately; teams that do not need Fluent styling can skip this dependency entirely.

The README's semver advice is specific: use a tilde range (~) for minor updates, which carry new features and fixes without breaking the public API; use a caret range (^) for major updates only, and expect major updates to include breaking API changes. For most integrations, tilde is the conservative default.

4.15.9 is the last build to include Internet Explorer support; current builds no longer support IE, and anyone still needing IE in production must pin to that specific earlier build.

ReactWebChat and FluentThemeProvider: the quick-start example does not show the experimental caveat

Web Chat exports ReactWebChat as a React component. The Fluent UI theme pack wraps it with FluentThemeProvider, which the README describes as designed for web developers who want to bring a native Copilot user experience to their customers. The README gives this embedding example:

import ReactWebChat from 'botframework-webchat';
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme';

export default function MyComponent() {
   return (
      <FluentThemeProvider>
         <ReactWebChat />
      </FluentThemeProvider>
   );
}

That example does not include any caveat, but reading further into the README reveals a note: the Fluent UI theme is currently in experimental phase, meaning it is not fully tested and may not cover all use cases. A team that stops at the quick-start example would not see that qualifier. This is the kind of detail that reads clearly in the full documentation but is not visible on a fast scan of the first code snippet.

Beyond the Fluent theme, Web Chat supports custom theme packs that developers can publish to NPM, packaging all customization into a single installable dependency rather than passing ad-hoc props at render time. Web Chat also exports through both ES Modules and CommonJS, with ES Modules using named exports for modern bundler pipelines.

styleOptions governs Adaptive Cards schema ceiling, Markdown HTML rendering, and file upload opt-out

Much of Web Chat's per-deployment configuration flows through a styleOptions object passed to the renderer, and several properties changed behavior in recent updates.

Adaptive Cards schema support has a configurable ceiling. The README shows setting adaptiveCardsParserMaxVersion to '1.2' as an example of locking to an older schema than the current default:

window.WebChat.renderWebChat(
   {
      directLine,
      store,
      styleOptions: {
         adaptiveCardsParserMaxVersion: '1.2'
      }
   },
   document.getElementById('webchat')
);

Passing an unrecognized string reverts to Web Chat's schema default. Markdown rendering now supports HTML inside Markdown with a sanitizer and accessibility fixer applied at the HTML level; bots that return HTML in Markdown will have it rendered rather than escaped, so operators who want Markdown-only output must actively opt out by passing `styleOptions.markdownRenderHTML` as false. File upload behavior changed to let users add a message before uploading, creating a confirmation step the old behavior did not have; to revert to the previous behavior, pass sendAttachmentOn: 'send' in styleOptions. Transcript accessibility has configurable focus border properties, including transcriptVisualKeyboardIndicatorColor and transcriptActivityVisualKeyboardIndicatorStyle.

Adaptive Cards support covers the current schema maximum; preview and non-Bot-Framework features are excluded

Web Chat supports Adaptive Cards up to schema 1.6. The README is explicit about what is not included: features in preview or designed for use outside Bot Framework are not supported by Web Chat. That exclusion is a stated design constraint, not a gap to be worked around in a future update.

For operators who need to stay on a constrained schema, adaptiveCardsParserMaxVersion in styleOptions sets the ceiling. Web Chat applies the maximum available schema by default, so passing a lower schema string locks a deployment to an earlier schema.

For teams comparing this approach to building a custom chat UI with DirectLine.js directly: Web Chat handles Adaptive Cards rendering, accessibility, and theme customization within its component layer. A DirectLine.js integration without Web Chat does not include those capabilities; the developer owns the full rendering pipeline. The trade-off is control against surface area: Web Chat owns the rendering decisions, and a custom DirectLine.js integration owns them entirely.

Content Security Policy is supported and recommended; repack packages pin exact builds of third-party dependencies

Web Chat documents support for Content Security Policy and recommends that web developers enable CSP to protect bot conversations. CSP matters for embedded chat components in particular, since the widget must load resources and communicate with a bot endpoint from inside a host page it does not control. Detailed CSP configuration instructions are in docs/CONTENT_SECURITY_POLICY.md in the repository root.

For a sense of the internal architecture: the repository is an NPM workspace with more than 20 packages, including core, component, api, styles, react-hooks, redux-store, directlinespeech, and bundle. Several repack packages vendor third-party dependencies, including adaptivecards, botframework-directlinejs, react, react-dom, and microsoft-cognitiveservices-speech-sdk. Rather than consuming those libraries directly from NPM, the project compiles its own controlled builds of each, pinning exact sources. That arrangement reduces exposure to upstream NPM changes but also means the project carries responsibility for keeping those controlled builds updated when upstream security fixes land.

The workspace includes DirectLine speech and debug tooling; the component layer does not handle bot logic

Beyond the core chat component, the workspace includes directlinespeech for voice-enabled bots, debug utilities, a debug theme, and packages for JSON-LD and graph operations. That range indicates Web Chat is designed to be the UI layer for a variety of bot communication protocols and media types, not just text-based chat.

One practical implication: Web Chat owns the rendering pipeline, not the bot logic. Custom activities extend the component by working with Web Chat's internal middleware and store APIs rather than just passing styleOptions, and developers who need to build custom activity renderers should read the samples directory, which includes examples for custom components and advanced UI recomposition.

The last push was on 2026-09-15, and the MIT licence applies to this repository.

Editorial conclusion

BotFramework-WebChat suits teams already in the Azure Bot Services or Bot Framework ecosystem who need a production-ready chat UI without building one from scratch. Skip it if your bot uses a different protocol, or if you need a chat UI not bound to Bot Framework's DirectLine protocol; a DirectLine.js integration without Web Chat gives more rendering control but carries the full surface area of building Adaptive Cards, accessibility, and theming independently. Before adopting, verify that the Bot Framework SDK archival does not affect the specific SDK features your bot depends on, and confirm Internet Explorer is not in your browser support matrix since Web Chat no longer supports it.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/BotFramework-WebChat on GitHub
3. Project website
4. README
5. Releases