How to use

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

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" role="main"></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' }),
        userID: 'YOUR_USER_ID'
      }, document.getElementById('webchat'));
    </script>
  </body>
</html>

If userID is not specified, it will be default to default-user. Multiple users sharing the same user ID is not recommended, their user state will be shared.

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" 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_BOT_SECRET' }),
        userID: 'YOUR_USER_ID'
      }, 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" role="main"></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' }),
        userID: 'YOUR_USER_ID'
      }, 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 } userID="YOUR_USER_ID" />
      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.

Official MockBot: we hosted a live demo bot for testing Web Chat features
Emulator Core: it will connect to http://localhost:5000/v3/directline for emulated Direct Line service

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

Samples list

Sample Name	Description	Link
`01.a.getting-started-full-bundle`	Introduces Web Chat embed from a CDN, and demonstrates a simple, full-featured Web Chat. This includes Adaptive Cards, Cognitive Services, and Markdown-It dependencies.	Demo
`01.b.getting-started-es5-bundle`	Introduces full-featured Web Chat embed with backwards compatibility for ES5 browsers using Web Chat's ES5 ponyfill.	Demo
`01.c.getting-started-migration`	Demonstrates how to migrate from your Web Chat v3 bot to v4.	Demo
`02.a.getting-started-minimal-bundle`	Introduces the minimized CDN with only basic dependencies. This does NOT include Adaptive Cards, Cognitive Services dependencies, or Markdown-It dependencies.	Demo
`02.b.getting-started-minimal-markdown`	Demonstrates how to add the CDN for Markdown-It dependency on top of the minimal bundle.	Demo
`03.a.host-with-react`	Demonstrates how to create a React component that hosts the full-featured Web Chat.	Demo
`03.b.host-with-Angular5`	Demonstrates how to create an Angular component that hosts the full-featured Web Chat.
`04.display-user-bot-initials-styling`	Demonstrates how to display initials for both Web Chat participants.	Demo
`04.b.display-user-bot-images-styling`	Demonstrates how to display images and initials for both Web Chat participants.	Demo
`05.a.branding-webchat-styling`	Introduces the ability to style Web Chat to match your brand. This method of custom styling will not break upon Web Chat updates.	Demo
`05.b.idiosyncratic-manual-styling`	Demonstrates how to make manual style changes, and is a more complicated and time-consuming way to customize styling of Web Chat. Manual styles may be broken upon Web Chat updates.	Demo
`05.c.presentation-mode-styling`	Demonstrates how to set up Presentation Mode, which displays chat history but does not show the send box, and disables the interactivity of Adaptive Cards.	Demo
`05.d.hide-upload-button-styling`	Demonstrates how to hide file upload button via styling.	Demo
`06.a.cognitive-services-bing-speech-js`	Introduces speech-to-text and text-to-speech ability using the (deprecated) Cognitive Services Bing Speech API and JavaScript.	Demo
`06.b.cognitive-services-bing-speech-react`	Introduces speech-to-text and text-to-speech ability using the (deprecated) Cognitive Services Bing Speech API and React.	Demo
`06.c.cognitive-services-speech-services-js`	Introduces speech-to-text and text-to-speech ability using Cognitive Services Speech Services API.	Demo
`06.d.speech-web-browser`	Demonstrates how to implement text-to-speech using Web Chat's browser-based Web Speech API. (link to W3C standard in the sample)	Demo
`06.e.cognitive-services-speech-services-with-lexical-result`	Demonstrates how to use lexical result from Cognitive Services Speech Services API.	Demo
`07.a.customization-timestamp-grouping`	Demonstrates how to customize timestamps by showing or hiding timestamps and changing the grouping of messages by time.	Demo
`07.b.customization-send-typing-indicator`	Demonstrates how to send typing activity when the user start typing on the send box.	Demo
`08.customization-user-highlighting`	Demonstrates how to customize the styling of activities based whether the message is from the user or the bot.	Demo
`09.customization-reaction-buttons`	Introduces the ability to create custom components for Web Chat that are unique to your bot's needs. This tutorial demonstrates the ability to add reaction emoji such as 👍 and 👎 to conversational activities.	Demo
`10.a.customization-card-components`	Demonstrates how to create custom activity card attachments, in this case GitHub repository cards.	Demo
`10.b.customization-password-input`	Demonstrates how to create custom activity for password input.	Demo
`11.customization-redux-actions`	Advanced tutorial: Demonstrates how to incorporate redux middleware into your Web Chat app by sending redux actions through the bot. This example demonstrates manual styling based on activities between bot and user.	Demo
`12.customization-minimizable-web-chat`	Advanced tutorial: Demonstrates how to add the Web Chat interface to your website as a minimizable show/hide chat box.	Demo
`13.customization-speech-ui`	Advanced tutorial: Demonstrates how to fully customize key components of your bot, in this case speech, which entirely replaces the text-based transcript UI and instead shows a simple speech button with the bot's response.	Demo
`14.customization-piping-to-redux`	Advanced tutorial: Demonstrates how to pipe bot activities to your own Redux store and use your bot to control your page through bot activities and Redux.	Demo
`15.a.backchannel-piggyback-on-outgoing-activities`	Advanced tutorial: Demonstrates how to add custom data to every outgoing activities.	Demo
`15.b.incoming-activity-event`	Advanced tutorial: Demonstrates how to forward all incoming activities to a JavaScript event for further processing.	Demo
`15.c.programmatic-post-activity`	Advanced tutorial: Demonstrates how to send a message programmatically.	Demo
`15.d.backchannel-send-welcome-event`	Advanced tutorial: Demonstrates how to send welcome event with client capabilities such as browser language.	Demo

Contributions

Like us? Star us.

Want to make it better? File us an issue.

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

Name		Name	Last commit message	Last commit date
Latest commit History 1,532 Commits
.github		.github
.vscode		.vscode
__tests__		__tests__
doc		doc
packages		packages
samples		samples
scripts		scripts
.babelrc		.babelrc
.dockerignore		.dockerignore
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
Dockerfile-playground		Dockerfile-playground
Dockerfile-testharness		Dockerfile-testharness
LICENSE		LICENSE
LOCALIZATION.md		LOCALIZATION.md
POC.md		POC.md
README.md		README.md
SAMPLES.md		SAMPLES.md
docker-compose.yml		docker-compose.yml
lerna.json		lerna.json
package-lock.json		package-lock.json
package.json		package.json
serve.json		serve.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

How to use

Integrate with JavaScript

Full bundle

Minimal bundle

Integrate with React

Customize Web Chat UI

Building the project

Build tasks

Testing Web Chat for development purpose

Building CDN bundle in development mode

Building CDN bundle in production mode

Samples list

Contributions

About

Releases

Packages

Languages

License

obot-ai/BotFramework-WebChat

Folders and files

Latest commit

History

Repository files navigation

How to use

Integrate with JavaScript

Full bundle

Minimal bundle

Integrate with React

Customize Web Chat UI

Building the project

Build tasks

Testing Web Chat for development purpose

Building CDN bundle in development mode

Building CDN bundle in production mode

Samples list

Contributions

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages