Customize Web Chat for your websites

Posted on by The Bot Framework Team

Every bot that is registered with the Bot Framework is automatically configured for the Web Chat channel. This channel includes the Web Chat control which can be embedded directly onto websites for users to interact with, for example – the assistant bot from the Microsoft Education homepage :

Most bot developers using the Bot Framework are well aware of this, but many are not aware of the different options available to you when embedding your bot to a website. As outlined in the bot documentation – Connect a bot to Web Chat the most common (and easiest) way to embed a bot to a website is using an iframe html element –

<iframe src="https://webchat.botframework.com/embed/YOUR_BOT_ID?t=YOUR_TOKEN_HERE"></iframe>

Web Chat instances provisioned this way are hosted by Microsoft. Although it is the easiest and most commonly used way to embed Web Chat control to websites currently, please be aware that there may be a lag behind the latest Web Chat release. In addition, implementing your own web chat instance provides you with greater control, allowing you to add custom styling (.css) and add features like speech which are currently limited with the standard Web Chat instance provided by <iframe>.

 Inline HTML

<!DOCTYPE html>
<html>
  <head>
    <link href="https://cdn.botframework.com/botframework-webchat/latest/botchat.css" rel="stylesheet" />
  </head>
  <body>
    <div id="bot"/>
    <script src="https://cdn.botframework.com/botframework-webchat/latest/botchat.js"></script>
    <script>
      BotChat.App({
        directLine: { secret: direct_line_secret },
        user: { id: 'userid' },
        bot: { id: 'botid' },
        resize: 'detect'
      }, document.getElementById("bot"));
    </script>
  </body>
</html>

The code sample above adds a DirectLine channel. You can get the DirectLine secret from the bot framework portal, as shown below.

In addition, the above code sample also provides default CDN script links to the latest versions of botchat.js and botchat.css. 

<script src="https://cdn.botframework.com/botframework-webchat/latest/botchat.js"></script>

<link href="https://cdn.botframework.com/botframework-webchat/latest/botchat.css" rel="stylesheet" />

 In order to customize Web Chat, you can clone the source code  and edit the typescript and scss files. After you’re done editing, from the root folder you can build Web Chat by runing the commands –

  1. npm install
  2. npm run build

The TypeScript files are compiled into ES6 standard, which is then bundled into javascript. More specifically, the following is built:

  • /built/*.js compiled from the TypeScript sources in /src/*.js – /built/BotChat.js is the root
  • /built/*.d.ts declarations for TypeScript users – /built/BotChat.d.ts is the root
  • /built/*.js.map sourcemaps for easier debugging
  • /botchat.js webpacked UMD file containing all dependencies (React, Redux, RxJS, polyfills, etc.)
  • /botchat.css base stylesheet
  • /botchat-fullwindow.css media query stylesheet for a full-window experience

Styling

If you only want to edit styling, within the/src/scss/ folder are all of the files associated with styling Web Chat. For basic branding, change colors.scss to match your color scheme. For advanced styling, change botchat.scss. You can run npm run build-css to compile to botchat.css.

Enabling Speech

To enable speech, you need to include the cognitive services library (included) into your HTML file, click here for a great example of how to enable speech. You can customize for whichever speech recognition and speech synthesis services you’d like:

var speechOptions = {
    speechRecognizer: new CognitiveServices.SpeechRecognizer( { subscriptionKey: 'YOUR_COGNITIVE_SPEECH_API_KEY' } ),

    speechSynthesizer: new CognitiveServices.SpeechSynthesizer(
        {
            subscriptionKey: 'YOUR_COGNITIVE_SPEECH_API_KEY',
            gender: CognitiveServices.SynthesisGender.Female,
            voiceName: 'Microsoft Server Speech Text to Speech Voice (en-US, JessaRUS)'
        })
}

...

BotChat.App({
    botConnection: botConnection,
    speechOptions: speechOptions,
    ...
}, document.getElementById("BotChatGoesHere"));

For more info, visit the documentation link – How to enable speech in Web Chat.

For React Apps

Web Chat also supports React components. In your React project, install the botframework-webchat npm module:

npm install botframework-webchat

After that, you simply include the Chat component –

Import { Chat } from 'botframework-webchat';

...

const YourApp = () => {
    <div>
        <YourComponent />
        <Chat directLine={{ secret: direct_line_secret }} user={{ id: 'user_id', name: 'user_name' }}/>
        <YourOtherComponent />
    </div>
}

...

This is automatically bundled for you when you run webpack to build your react application.

Open Source

For more details, check out the README from the GitHub Repo linked below:

Web Chat on Github

Web Chat is also open source! We welcome and accept community contributions and feedback, whether it’s for new features, bug fixes, or support. In fact, here’s some other open source code bases affiliated with the Bot Framework freely available on GitHub:

Bot Builder SDK 

Bot Framework Samples

Adaptive Cards

Recognizers-Text

Bot Framework Emulator 

Bot Builder SDK Azure Extensions

Bing Location Control for Microsoft Bot Framework

Happy Making!

The Bot Framework team.

Posted in Bot Framework