Web Chat overview

  • Article

APPLIES TO: SDK v4

This article contains details of 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.

If you're looking to migrate from Web Chat v3 to v4, jump ahead to the migration section.

Get started with Web Chat

Note

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

First, create a bot using Azure AI Bot Service. Once the bot is created, you'll 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.

The following example shows how to add a Web Chat control to a website.

<!DOCTYPE html>
<html>
   <body>
      <div id="webchat" role="main"></div>
      <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
      <script>

         // Set style options.
         const styleOptions = {
            botAvatarInitials: 'BF',
            userAvatarInitials: 'WC'
         };

         window.WebChat.renderWebChat(
            {
               directLine: window.WebChat.createDirectLine({
                  token: 'YOUR_DIRECT_LINE_TOKEN'
               }),
               userID: 'YOUR_USER_ID',
               username: 'Web Chat User',
               locale: 'en-US',
               styleOptions
            },
            document.getElementById('webchat')
         );
      </script>
   </body>
</html>

Note

userID, username, locale, botAvatarInitials, and userAvatarInitials are all optional parameters to pass into the renderWebChat method. For more information about style, see Why styleOptions?. To learn more about Web Chat properties, look at the Web Chat API Reference section.

Integrate with JavaScript

Web Chat is designed to integrate with your existing website using JavaScript or React. Integrating with JavaScript will give you some styling and customizability, for more information, see Integrate Web Chat into your website.

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

<!DOCTYPE html>
<html>
   <body>
      <div id="webchat" role="main"></div>
      <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
      <script>
         window.WebChat.renderWebChat(
            {
               directLine: window.WebChat.createDirectLine({
                  token: 'YOUR_DIRECT_LINE_TOKEN'
               }),
               userID: 'YOUR_USER_ID'
            },
            document.getElementById('webchat')
         );
      </script>
   </body>
</html>

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 { DirectLine } from 'botframework-directlinejs';
import React from 'react';
import ReactWebChat from 'botframework-webchat';

export default class extends React.Component {
  constructor(props) {
    super(props);

    this.directLine = new DirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' });
  }

  render() {
    return (
      <ReactWebChat directLine={ this.directLine } userID='YOUR_USER_ID' />
      element
    );
  }
}

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 a working sample of Web Chat rendered via React.

Tip

If you're new to React and jsx you can find training on Reacts Getting Started page.

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're importing Web Chat in different ways. This list isn't exhaustive.

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

Note

For information on Content Delivery Networks (CDNs) See Content delivery networks (CDNs)

Migrating from Web Chat v3 to v4

There are three possible paths that migration might take when migrating from v3 to v4. Compare your beginning scenario with the one listed below.

  • To upgrade a Web Chat control embedded in an <iframe>, see the documentation in the Web Chat repo for the embed package.
  • To upgrade a Web Chat control that uses little to no customization, review the Web Chat 00.migration/a.v3-to-v4 sample, which describes the process.
  • To upgrade a forked version of a highly customized Web Chat, see the Web Chat migration guidance.

Web Chat API Reference

There are several properties that you might pass into your Web Chat React Component (<ReactWebChat>) or the renderWebChat() method. For a short description of the available properties, see Web Chat API Reference. Also, feel free to examine the source code starting with packages/component/src/Composer.js.

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, see the ES5 bundle and demo.

  • Web Chat doesn't support Internet Explorer older than version 11
  • Customization as shown in non-ES5 samples aren't supported for Internet Explorer. Because IE11 is a non-modern browser, it doesn't support ES6, and many samples that use arrow functions and modern promises would need to be manually converted to ES5. If you're 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 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 hasn't yet been released, you'll 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'll 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 myget.org

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=https://botbuilder.myget.org/F/botframework-webchat/npm/
  4. Add Web Chat to your project dependencies npm i botframework-webchat --save
  5. 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 npmjs.com.

Resubscribe to official release on npmjs.com

Resubscribing 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. In your package-lock.json, the registries are pointing to https://npmjs.com/ again.

Contributing

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 opencode@microsoft.com with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you don't, follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.