A highly-customizable web-based client for Azure Bot Services.
Clone or download
compulim Add visual regression test and code coverage report (#1323)
* Add WebDriver test

* Auto host web server

* Clean up

* Clean up

* Add visual regression test

* Clean up

* Clean up

* Add chrome-docker

* Run Chrome in Docker

* Add coveralls

* Run WebDriver in detached mode

* Comment out slow part

* Debug coverage

* Build instrumented build

* Build instrumented build separately

* Reduce concurrently

* Include both instrumented and production build in Docker

* Fix coverage reporting

* Add badge

* Cleanup

* Update CHANGELOG.md

* Clean up

* Typo
Latest commit 80a3a57 Nov 8, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Merge preview into master (#1277) Oct 31, 2018
__tests__ Add visual regression test and code coverage report (#1323) Nov 8, 2018
doc Merge preview into master (#1277) Oct 31, 2018
packages Add visual regression test and code coverage report (#1323) Nov 8, 2018
samples Bump dependencies (#1303) Nov 4, 2018
scripts Sample: Minimize mode sample (#1290) Nov 2, 2018
.babelrc Add visual regression test and code coverage report (#1323) Nov 8, 2018
.dockerignore Merge preview into master (#1277) Oct 31, 2018
.gitignore Add visual regression test and code coverage report (#1323) Nov 8, 2018
.travis.yml Add visual regression test and code coverage report (#1323) Nov 8, 2018
CHANGELOG.md Add visual regression test and code coverage report (#1323) Nov 8, 2018
Dockerfile-playground Add visual regression test and code coverage report (#1323) Nov 8, 2018
Dockerfile-testharness Add visual regression test and code coverage report (#1323) Nov 8, 2018
LICENSE Merge preview into master (#1277) Oct 31, 2018
LOCALIZATION.md Merge preview into master (#1277) Oct 31, 2018
POC.md Merge preview into master (#1277) Oct 31, 2018
README.md Add visual regression test and code coverage report (#1323) Nov 8, 2018
SAMPLES.md Use webchat.js as bundle name (#1285) Nov 1, 2018
docker-compose.yml Add visual regression test and code coverage report (#1323) Nov 8, 2018
lerna.json Sample: Minimize mode sample (#1290) Nov 2, 2018
package-lock.json Add visual regression test and code coverage report (#1323) Nov 8, 2018
package.json Add visual regression test and code coverage report (#1323) Nov 8, 2018
serve.json Use webchat.js as bundle name (#1285) Nov 1, 2018

README.md

Azure Bot Services logo

A highly-customizable web-based client for Azure Bot Services.

npm version Build Status Coverage Status

How to use

For previous versions of Web Chat (v3), you can find it here.

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 to use in the code below.

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

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

Screenshot of Web Chat

Integrate with JavaScript

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

Full bundle

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

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

See a working sample with full Web Chat bundle here.

Minimal bundle

Instead of using the full, typical package of Web Chat, you can choose a lighter-weight sample with fewer features. This bundle does not contain:

  • Adaptive Cards
  • Cognitive Services
  • Markdown-It

Since Adaptive Cards is not include in this bundle, rich cards that depends on Adaptive Cards will not render, e.g. hero card, receipt card, etc. List of attachments that are not supported without Adaptive Cards can be found here.

See a working sample with minimal Web Chat bundle here.

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

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_BOT_SECRET' });
  }

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

You can also run npm install botframework-webchat@master to install a development build that sync with GitHub master branch.

See a working sample with Web Chat rendered by React here.

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 Yes Yes
Change sizes Yes Yes
Update/replace CSS styles Yes Yes
Listen to events Yes Yes
Interact with hosting webpage Yes Yes
Custom render activities Yes
Custom render attachments Yes
Add new UI components Yes
Recompose the whole UI Yes

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

Building the project

If you need to build this project for customization purpose, we strongly advise you to refer to our samples. If you cannot find any samples that could fulfill your customization needs and you don't know how to do that, please send your dream to us.

Forking Web Chat for customizations means you will lose access to our latest updates. And maintaining forks also introduce chores that is substantially more complicated than version bump.

To build Web Chat, you will need to make sure both your Node.js and NPM is latest version (either LTS or current).

npm install
npm run bootstrap
npm run build

Build tasks

There are 3 types of build tasks in the build process.

  • npm run build: Build for development (instrumented code for code coverage)
    • Will bundle as webchat-instrumented*.js
  • npm run watch: Build for development with watch mode loop
  • npm run prepublishOnly: Build for production
    • Will bundle as webchat*.js

Testing Web Chat for development purpose

We built a playground app for testing Web Chat so we can test certain Web Chat specific features.

cd packages/playground
npm start

Then browse to http://localhost:3000/, and click on one of the connection options on upper right corner.

You are also advised to test the CDN bundles by copying the test harness from our samples.

Building CDN bundle in development mode

Currently, the standard build script does not build CDN bundle (webchat*.js).

cd packages/bundle
npm run webpack-dev

By default, this script will run in watch mode.

Building CDN bundle in production mode

If you want to build a production CDN bundle with minification, you can follow these steps.

cd packages/bundle
npm run prepublishOnly

Contributions

Like us? Star us.

Want to make it better? File us an issue.

Don't like something you see? Submit a pull request.