Skip to content
A highly-customizable web-based client for Azure Bot Services.
JavaScript TypeScript HTML Other
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Reset build script (#2767) Jan 15, 2020
.vscode Merge preview into master (#1277) Oct 31, 2018
__tests__ Fix call downstream middleware twice (#2839) Jan 23, 2020
docs Fix locale prop for Localization (#2854) Jan 24, 2020
media Add screencaps for filing new issues (#2070) Jun 11, 2019
packages Fix call downstream middleware twice (#2839) Jan 23, 2020
samples Fixed CDN link (#2849) Jan 23, 2020
scripts 2794 & 2510 Fix change local, hybrid react, and clear after idle samp… Jan 6, 2020
.dockerignore Reset build script (#2767) Jan 15, 2020
.eslintrc.yml Move to prettier! (#2038) Jun 3, 2019
.gitignore udpates for //build May 5, 2019
.prettierrc.yml Reset build script (#2767) Jan 15, 2020
.travis.yml Reset build script (#2767) Jan 15, 2020 Fix call downstream middleware twice (#2839) Jan 23, 2020
Dockerfile-playground Use locally built files (#1642) Jan 26, 2019
Dockerfile-selenium Reset build script (#2767) Jan 15, 2020
Dockerfile-testharness Add visual regression test and code coverage report (#1323) Nov 8, 2018
LICENSE Merge preview into master (#1277) Oct 31, 2018 Adding Arabic localization support (#2593) Nov 25, 2019 Update supported channels (#2851) Jan 24, 2020
azure-pipelines.yml Reset build script (#2767) Jan 15, 2020
babel-jest-config.js Reset build script (#2767) Jan 15, 2020
babel.config.json Reset build script (#2767) Jan 15, 2020
docker-compose.yml Reset build script (#2767) Jan 15, 2020
jest.config.js Reset build script (#2767) Jan 15, 2020
lerna.json Reset build script (#2767) Jan 15, 2020
package-lock.json Reset build script (#2767) Jan 15, 2020
package.json Reset build script (#2767) Jan 15, 2020
serve.json Reset build script (#2767) Jan 15, 2020

Bot Framework Web Chat

Click here to find out what is new in Web Chat

Bot Framework Web Chat

npm version Build Status Coverage Status

This repository contains code for the Bot Framework Web Chat component. The Bot Framework Web Chat component is a highly-customizable web-based client for the Bot Framework V4 SDK. The Bot Framework SDK v4 enables developers to model conversation and build sophisticated bot applications.

This repo is part of the Microsoft Bot Framework - a comprehensive framework for building enterprise-grade conversational AI experiences.

Upgrading to 4.6.0

Starting from Web Chat 4.6.0, Web Chat requires React 16.8.6 or up.

Although we recommend that you upgrade your host app at your earliest convenience, we understand that host app may need some time before its React dependencies are updated, especially in regards to huge applications.

If your app is not ready for React 16.8.6 yet, you can follow this sample to dual-host React in your app.

Speech changes in Web Chat 4.5.0

There is a breaking change on behavior expectations regarding speech and input hint in Web Chat. Please refer to this section on input hint behavior before 4.5.0 for details.

Migrating from Web Chat v3 to v4

View migration docs to learn about migrating from Web Chat v3.

How to use

For previous versions of Web Chat (v3), visit the Web Chat v3 branch documentation.

First, create a bot using Azure Bot Service. Once the bot is created, you will need to obtain the bot's Web Chat secret in Azure Portal. Then use the secret to generate a token and pass it to your Web Chat.

Integrate with JavaScript

Web Chat is designed to integrate with your existing website using JavaScript or React. Integrating with JavaScript will give you moderate styling and customizability.

You can use the full, typical webchat package that contains the most typically used features.

Here is how how you can add Web Chat control to your website:

<!DOCTYPE html>
      <script src=""></script>
         body {
            height: 100%;

         body {
            margin: 0;

         #webchat {
            height: 100%;
            width: 100%;
      <div id="webchat" role="main"></div>
               directLine: window.WebChat.createDirectLine({
                  token: 'YOUR_DIRECT_LINE_TOKEN'
               userID: 'YOUR_USER_ID',
               username: 'Web Chat User',
               locale: 'en-US',
               botAvatarInitials: 'WC',
               userAvatarInitials: 'WW'

userID, username, locale, botAvatarInitials, and userAvatarInitials are all optional parameters to pass into the renderWebChat method. To learn more about Web Chat props, look at the Web Chat API Reference section of this README.

Screenshot of Web Chat

See the working sample of the full Web Chat bundle.

Integrate with React

For full customizability, you can use React to recompose components of Web Chat.

To install the production build from NPM, run npm install botframework-webchat.

import React, { useMemo } from 'react';
import ReactWebChat, { createDirectLine } from 'botframework-webchat';

export default () => {
   const directLine = useMemo(() => createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }), []);

   return <ReactWebChat directLine={directLine} userID="YOUR_USER_ID" />;

You can also run npm install botframework-webchat@master to install a development build that is synced with Web Chat's GitHub master branch.

See the working sample of Web Chat rendered via React.

Integrate with Cognitive Services Speech Services

You can use Cognitive Services Speech Services to add bi-directional speech functionality to Web Chat. Please refer to this article about using Cognitive Services Speech Services for details.

Customize Web Chat UI

Web Chat is designed to be customizable without forking the source code. The table below outlines what kind of customizations you can achieve when you are importing Web Chat in different ways. This list is not exhaustive.

CDN bundle React
Change colors
Change sizes
Update/replace CSS styles
Listen to events
Interact with hosting webpage
Custom render activities
Custom render attachments
Add new UI components
Recompose the whole UI

See more about customizing Web Chat to learn more on customization.

Supported Activity Types on the Web Chat Client

Bot Framework has many activity types, but not all are supported in Web Chat. View activity types docs to learn more.

Samples list

View the complete list of Web Chat samples for more ideas on customizing Web Chat.

Web Chat API Reference

View the API documentation for implementing Web Chat.

Browser compatibility

Web Chat supports the latest 2 versions of modern browsers like Chrome, Edge, and FireFox. If you need Web Chat in Internet Explorer 11, please see the ES5 bundle demo.

Please note, however:

  • Web Chat does not support Internet Explorer older than version 11
  • Customization as shown in non-ES5 samples are not supported for Internet Explorer. Because IE11 is a non-modern browser, it does not support ES6, and many samples that use arrow functions and modern promises would need to be manually converted to ES5. If you are in need of heavy customization for your app, we strongly recommend developing your app for a modern browser like Google Chrome or Edge.
  • Web Chat has no plan to support samples for IE11 (ES5).
    • For customers who wish to manually rewrite our other samples to work in IE11, we recommend looking into converting code from ES6+ to ES5 using polyfills and transpilers like babel.

How to connect a client app to bot

Web Chat provides UI on top of the Direct Line and Direct Line Speech Channels. There are two ways to connect to your bot through HTTP calls from the client: by sending the Bot secret or generating a token via the secret.

We strongly recommend using the token API instead of providing the app with your secret. To learn more about why, see the authentication documentation on the token API and client security.

For further reading, please see the following links:

How to test with Web Chat's latest bits

Testing unreleased features is only available via MyGet packaging at this time.

If you want to test a feature or bug fix that has not yet been released, you will want to point your Web Chat package to Web Chat's daily feed, as opposed the official npmjs feed.

Currently, you may access Web Chat's dailies by subscribing to our MyGet feed. To do this, you will need to update the registry in your project. This change is reversible, and our directions include how to revert back to subscribing to the official release.

Subscribe to latest bits on

To do this you may add your packages and then change the registry of your project.

  1. Add your project dependencies other than Web Chat.
  2. In your project's root directory, create a .npmrc file
  3. Add the following line to your file: registry=
  4. Add Web Chat to your project dependencies npm i botframework-webchat --save
  5. Note that in your package-lock.json, the registries pointed to are now MyGet. The Web Chat project has upstream source proxy enabled, which will redirect non-MyGet packages to

Re-subscribe to official release on

Re-subscribing requires that you reset your registry.

  1. Delete your .npmrc file
  2. Delete your root package-lock.json
  3. Remove your node_modules directory
  4. Reinstall your packages with npm i
  5. Note that in your package-lock.json, the registries are pointing to again.


See our Contributing page for details on how to build the project and our repository guidelines for Pull Requests.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.

Reporting Security Issues

View the security documentation to learn more about reporting security issues.

You can’t perform that action at this time.