markdown-body entry-content container-lg" itemprop="text">

Click here to find out what is new in Web Chat

Bot Framework Web Chat

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 repository is part of the Microsoft Bot Framework - a comprehensive framework for building enterprise-grade conversational AI experiences.

Web Chat supports Content Security Policy (CSP). Web developers are recommended to enable CSP to improve security and protect conversations. You can read more about CSP in this article.

Version notes

This section points out important version notes. For further information, please see the related links and check the CHANGELOG.md

4.12.1 patch: New style property `adaptiveCardsParserMaxVersion`

Web Chat 4.12.1 patch includes a new style property allowing developers to choose the max Adaptive Cards schema version. See PR #3778 for code changes.

To specify a different max version, you can adjust the style options, shown below:

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

Web Chat will apply the maximum schema available according to the Adaptive Cards version (as of this patch, schema 1.3) by default.
An invalid version will revert to Web Chat's default.

Visual focus changes to transcript in Web Chat 4.12.0

A new accessibility update has been added to Web Chat from PR #3703. This change creates visual focus for the transcript (bold black border) and aria-activedescendent focused activity (black dashed border) by default. Where applicable, transcriptVisualKeyboardIndicator... values will also be applied to carousel (CarouselFilmStrip.js) children. This is done in order to match current default focus styling for Adaptive Cards, which may be a child of a carousel.

To modify these styles, you can change the following props via styleOptions:

  transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
  transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
  transcriptActivityVisualKeyboardIndicatorWidth: 1,
  transcriptVisualKeyboardIndicatorColor: 'Black',
  transcriptVisualKeyboardIndicatorStyle: 'solid',
  transcriptVisualKeyboardIndicatorWidth: 2,

The above code shows the default values you will see in Web Chat.

API refactor into new package in Web Chat 4.11.0

The Web Chat API has been refactored into a separate package. To learn more, check out the API refactor summary.

Direct Line Speech support in Web Chat 4.7.0

Starting from Web Chat 4.7.0, Direct Line Speech is supported, and it is the preferred way to provide an integrated speech functionality in Web Chat. We are working on closing feature gaps between Direct Line Speech and Web Speech API (includes Cognitive Services and browser-provided speech functionality).

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 the hybrid React 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 the 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

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.

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:

Using Web Chat with Azure Bot Services authentication
Enhanced Direct Line authentication features

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 options.

You can use the full, typical Web Chat package (called full-feature bundle) that contains the most typically used features.

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

<!DOCTYPE html>
<html>
  <head>
    <script
      crossorigin="anonymous"
      src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"
    ></script>
    <style>
      html,
      body {
         height: 100%;
      }

      body {
        margin: 0;
      }

      #webchat {
        height: 100%;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="webchat" role="main"></div>
    <script>
      window.WebChat.renderWebChat(
        {
          directLine: window.WebChat.createDirectLine({
            token: 'YOUR_DIRECT_LINE_TOKEN'
          }),
          userID: 'YOUR_USER_ID',
          username: 'Web Chat User',
          locale: 'en-US'
        },
        document.getElementById('webchat')
      );
    </script>
  </body>
</html>

userID, username, and locale are all optional parameters to pass into the renderWebChat method. To learn more about Web Chat props, look at the Web Chat API Reference documentation.

Assigning userID as a static value is not recommended since this will cause all users to share state. Please see the API userID entry for more information.

More information on localization can be found in the Localization documentation.

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@main to install a development build that is synced with Web Chat's GitHub main branch.

See the working sample of Web Chat rendered via React.

Experimental support for Redux DevTools

Web Chat internally use Redux for state management. Redux DevTools is enabled in the NPM build as an opt-in feature.

This is for glancing into how Web Chat works. This is not an API explorer and is not an endorsement of using the Redux store to programmatically access the UI. The hooks API should be used instead.

To use Redux DevTools, use the createStoreWithDevTools function for creating a Redux DevTools-enabled store.

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

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

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

There are some limitations when using the Redux DevTools:

The Redux store uses side-effects via redux-saga. Time-traveling may break the UI.
Many UI states are stored in React context and state. They are not exposed in the Redux store.
Some time-sensitive UIs are based on real-time clock and not affected by time-traveling.
Dispatching actions are not officially supported. Please use hooks API instead.
Actions and reducers may move in and out of Redux store across versions. Hooks API is the official API for accessing the UI.

Customizing the 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.

How to test with Web Chat's latest bits

Web Chat latest bits are available on the Web Chat daily releases page.

Dailies will be released after 3:00AM Pacific Standard Time when changes have been committed to the main branch.

Contributing

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

See our CODE OF CONDUCT page for details about the Microsoft Code of Conduct.

Reporting Security Issues

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

Click here to find out what is new in Web Chat

Bot Framework Web Chat

Version notes

4.12.1 patch: New style property `adaptiveCardsParserMaxVersion`

Visual focus changes to transcript in Web Chat 4.12.0

API refactor into new package in Web Chat 4.11.0

Direct Line Speech support in Web Chat 4.7.0

Upgrading to 4.6.0

Speech changes in Web Chat 4.5.0

Migrating from Web Chat v3 to v4

How to use

Connect a client app to bot

Integrate with JavaScript

Integrate with React

Experimental support for Redux DevTools

Customizing the Web Chat UI

Supported Activity Types on the Web Chat Client

Samples list

Further reading

API Reference

Browser compatibility

Accessibility

Localization

Notifications

Telemetry

Technical Support Guide

Speech

Integrate with Direct Line Speech

Integrate with Cognitive Services Speech Services

Browser-provided engine or other engines

How to test with Web Chat's latest bits

Contributing

Reporting Security Issues

Click here to find out what is new in Web Chat

Bot Framework Web Chat

Version notes

4.12.1 patch: New style property adaptiveCardsParserMaxVersion

Visual focus changes to transcript in Web Chat 4.12.0

API refactor into new package in Web Chat 4.11.0

Direct Line Speech support in Web Chat 4.7.0

Upgrading to 4.6.0

Speech changes in Web Chat 4.5.0

Migrating from Web Chat v3 to v4

How to use

Connect a client app to bot

Integrate with JavaScript

Integrate with React

Experimental support for Redux DevTools

Customizing the Web Chat UI

Supported Activity Types on the Web Chat Client

Samples list

Further reading

API Reference

Browser compatibility

Accessibility

Localization

Notifications

Telemetry

Technical Support Guide

Speech

Integrate with Direct Line Speech

Integrate with Cognitive Services Speech Services

Browser-provided engine or other engines

How to test with Web Chat's latest bits

Contributing

Reporting Security Issues

4.12.1 patch: New style property `adaptiveCardsParserMaxVersion`

License

microsoft/BotFramework-WebChat

About

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases 64

Packages 0

Used by 646

Contributors 107

Languages

Packages