Botframework Webchat
A highly-customizable web-based client for Azure Bot Services.
Last verified:
What is Botframework Webchat?
Botframework Webchat is a highly-customizable web-based client for the Bot Framework V4 SDK and Azure AI Bot Service. It provides a conversational UI component that developers can embed into websites and web applications to enable users to interact with AI bots through text and speech. The SDK v4 enables developers to model conversations and build sophisticated bot applications with natural language understanding.
Key features include full UI customization through StyleSet properties (colors, fonts, sizes, layout), React component recomposition for advanced customization, Direct Line and Direct Line Speech channel support, Adaptive Cards up to schema 1.6, HTML-in-Markdown rendering, livestreaming responses, file upload with confirmation, theme pack support including experimental Fluent UI theme, Content Security Policy (CSP) support, Redux-based state management, localization support, speech integration with multiple engines, accessibility features with visual focus indicators, and npm/CDN distribution options.
Web Chat is designed for web developers, bot developers, and enterprises building conversational AI experiences. It serves developers who need to embed bot functionality into websites, customer service teams building chat interfaces, organizations creating Microsoft Teams integrations, and developers building white-label conversational experiences. The tool supports both JavaScript integration for moderate customization and React integration for full customizability.
The component supports modern browsers (latest 2 versions of Chrome, Edge, Firefox), integrates with Azure AI Bot Service, and provides enterprise-grade security with token-based authentication. It includes built-in support for rich cards, attachments, avatars, carousel components, and comprehensive event listening capabilities for interacting with the hosting webpage.
Botframework Webchat pricing
Pricing model: Freemium
Bot Framework Web Chat is free and open source under the MIT license. The component is available via npm (botframework-webchat package) and CDN (https://cdn.botframework.com/botframework-webchat/latest/webchat.js) at no cost. Azure AI Bot Service may have associated Azure hosting costs, but the Web Chat client itself is free. Development builds are available via MyGet daily feeds. No paid tiers or enterprise licensing required for the Web Chat component.
Botframework Webchat pros
- Highly customizable UI without forking source code
- Supports both JavaScript and React integration
- Full StyleSet control over colors, fonts, sizes, and layout
- React allows recomposing entire UI components
- Direct Line Speech support for integrated speech functionality
- Adaptive Cards schema support up to version 1.6
- HTML-in-Markdown rendering with security sanitization
- Livestreaming response support for bots
- Theme pack support including experimental Fluent UI theme
- File upload with user confirmation before sending
- Content Security Policy (CSP) support for security
- Redux DevTools support for debugging
- Localization support for multiple languages
- Multiple speech engine options (Direct Line, Cognitive Services, browser-based)
- Accessibility features with visual keyboard indicators
- CDN bundle for easy JavaScript integration
- npm package available for production builds
- Open source with MIT license
- Active Microsoft maintenance and regular updates
Botframework Webchat cons
- Internet Explorer 11 no longer supported since version 4.16.0
- Requires React 16.8.6 or higher for React integration
- Heavy customization requires modern browser (Chrome/Edge recommended)
- IE11 customization limited to ES5 bundle only
- No plan to support IE11 ES5 samples
- Redux DevTools has time-traveling limitations that may break UI
- Some Adaptive Cards features in preview are not supported
- Assigning static userID causes all users to share state
- Direct Line token management required for security
- Daily bits only available via MyGet packaging for testing
Frequently asked questions about Botframework Webchat
What is Bot Framework Web Chat?
Bot Framework Web Chat is a highly-customizable web-based client for the Bot Framework V4 SDK. It provides a conversational UI component that developers can embed into websites and web applications, enabling users to interact with AI bots through text and speech. The SDK v4 enables developers to model conversations and build sophisticated bot applications.
How do I integrate Web Chat into my website?
You can integrate Web Chat using JavaScript via CDN by adding a script tag pointing to https://cdn.botframework.com/botframework-webchat/latest/webchat.js and calling window.WebChat.renderWebChat() with your Direct Line token. For full customizability, install the npm package (npm install botframework-webchat) and use the ReactWebChat component with your DirectLine instance.
What browsers does Web Chat support?
Web Chat supports the latest 2 versions of modern browsers including Chrome, Microsoft Edge, and Firefox. Internet Explorer 11 was supported until version 4.15.9, but version 4.16.0 and later no longer support Internet Explorer. For heavy customization, Microsoft strongly recommends developing for modern browsers like Chrome or Edge.
How do I customize the Web Chat UI appearance?
Web Chat is customizable without forking source code. You can change colors, sizes, and CSS styles using both CDN bundle and React. For CDN, pass styleOptions to renderWebChat() with properties like backgroundColor, botAvatarInitials, and userAvatarInitials. For React, use createStyleSet() with StrictStyleOptions to control accent colors, fonts, and layout. React allows custom rendering of activities, attachments, and adding new UI components.
What authentication method should I use for Web Chat?
Microsoft strongly recommends using the token API instead of providing the app with your bot secret. You obtain the bot's Web Chat secret from the Azure Portal, then use it to generate a token which you pass to Web Chat via createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }). This is more secure than exposing the bot secret directly in client-side code.
Does Web Chat support speech functionality?
Yes, Web Chat supports multiple speech engines. Direct Line Speech is the preferred way to add integrated speech functionality starting from version 4.7.0. You can also use Cognitive Services Speech Services or browser-provided speech engines that support the W3C Web Speech API standard (Speech Recognition API and Speech Synthesis API). You can mix-and-match different engines for the best user experience.
What is the difference between CDN bundle and React integration?
CDN bundle integration provides moderate styling and customizability - you can change colors, sizes, update CSS styles, listen to events, and interact with the hosting webpage. React integration provides full customizability - in addition to CDN features, you can custom render activities, custom render attachments, add new UI components, and recompose the entire UI. React requires npm installation and React 16.8.6 or higher.
How do I handle file uploads in Web Chat?
Starting from version 4.17.0, end-users can add a message and confirm before uploading their file to the bot, improving the file upload experience. To opt-out of this new confirmation experience and send attachments immediately, pass sendAttachmentOn: 'send' in your styleOptions when rendering Web Chat.
What Adaptive Cards version does Web Chat support?
Web Chat 4.16.1 supports Adaptive Cards schema up to version 1.6. Some features in Adaptive Cards are in preview or designed for use outside Bot Framework and are not supported. You can specify a different max version using the adaptiveCardsParserMaxVersion style option, such as setting it to '1.2'. An invalid version will revert to Web Chat's default (schema 1.3 as of patch 4.12.1).
How do I test unreleased features or latest bits in Web Chat?
Testing unreleased features is available via MyGet packaging. Create a .npmrc file in your project root and add registry=https://botbuilder.myget.org/F/botframework-webchat/npm/. Then install with npm i botframework-webchat --save. Daily releases are available after 3:00 AM Pacific Standard Time when changes are committed to the main branch. To revert to official npmjs.com releases, delete .npmrc, delete package-lock.json, remove node_modules, and run npm i.