@arvato-crm/acai-chatwidget

ACAI Chat Widget for BotFramework-WebChat

Usage no npm install needed!

<script type="module">
  import arvatoCrmAcaiChatwidget from 'https://cdn.skypack.dev/@arvato-crm/acai-chatwidget';
</script>

README

ACAI-ChatWidget

Built with love

An easy to use web widget for the Microsoft Bot Framework Web Chat

Usage

The ACAI-ChatWidget can be used in two ways:

  • in a pure HTML website (no webpack/npm or any other module system)
  • in a web application as npm package

HTML page

Currently there is no CDN to deliver the bundle. You can build a ACAI-ChatWidget release (see below) and use the js and css file from ./dist/ folder.

Place the files on your server and link to them:

<head>
    <script src="acai-chatwidget.js"></script>
    <link href="acai-chatwidget.css" rel="stylesheet" />
</head>
<body>
    ...
    <!-- DIV tag must be above initialization script -->
    <div id="BotChatGoesHere"></div>

    <script>
        var botChatDiv = document.getElementById('BotChatGoesHere');

        var config = {
            // use example config from section Configuration below
            ...
        }

        ACAI.ChatWidget(config, botChatDiv);
    </script>
    ...
</body>

Build release

  • Checkout from acai repository
  • Change into acai/acai-chatwidget
  • Run npm install to download all dependencies
  • Run npm run build:release to build a release
  • Release will be available at ./dist/

Example

You can find a complete example in ./demo/index.html. You only have to set directLineSecret and botId.
Run npm run build:watch to build a ACAI-ChatWidget release and open the HTML in your Browser.

npm package

You need to use our own Nexus server https://nexus.iaas-at-mit.de/ and one of the following repositories in your .npmrc

.npmrc

...
registry=https://nexus.iaas-at-mit.de/content/groups/npm-all/
...

Install the ACAI-ChatWidget via npm install --save @arvato-crm/acai-chatwidget and use following code to include it in your JavaScript:

import * as ACAI from 'acai-chatwidget';
import 'acai-chatwidget/dist/acai-chatwidget.css';

var botChatDiv = document.getElementById('BotChatGoesHere');

var config = {
    // use example config from section Configuration below
    ...
}

ACAI.ChatWidget(config, botChatDiv);

Example

You can find a complete example in the acai git repository under acai/acai-chatwidget-npm-example. Open the readme.md to find information how the example works.

Configuration

The necessary configuration contains following entries:

var config = {
    botChat: {
        directLineSecret: '<secret>', // Direct Line Secret for Microsoft Bot Framework Web Chat
        botId: 'MyBot', // ID of this bot
        userId: '0815', // [optional] ID of user, if not set a random userId will be used
        userName: 'Customer', // [optional] name of user, it not set the userId will  be used
        initialMessage: '42' // [optional] initial message to trigger response from bot
    },
    ui: {
        bubbleDelay: 2000, // delay until bubble is shown
        bubbleTextDelay: 2500, // delay until text at bubble is shown
        bubbleText: 'Whazaaaap?!', // label in bubble text
        chatTitle: 'Your ad here' // label in sidebar chat title
    }
}

Styling

The easiest way to create a custom style for ACAI-ChatWidget is to use the acai-chatwidget.scss file from ./res/:

  • Copy the SASS file from this repo to your own project and call it acai-chatwidget-override.scss
  • Modify the file at your wishes
    • You can define font, colors and spaces easily with variables
    • Don't forget to create your own icons and set the icon files in the corresponding variables
  • Depending on your usage of ACAI-ChatWidget use one of the following ways to include the new style file to your page

HTML page

Compile the new sass file acai-chatwidget-override.scss to css with a tool of your choice and link to it in your HTML after acai-chatwidget.css:

<head>
    <script src="acai-chatwidget.js"></script>
    <link href="acai-chatwidget.css" rel="stylesheet" />
    <link href="acai-chatwidget-override.css" rel="stylesheet" />
</head>

npm package

Add sass-loader to your project if not present and configure webpack to load .scss files. Import the acai-chatwidget-override.scss after acai-chatwidget.css:

import * as ACAI from 'acai-chatwidget';
import 'acai-chatwidget/dist/acai-chatwidget.css';
import '<path>/acai-chatwidget-override.scss';

Development

Source code needed 😉

on-the-fly development

Useful to develop the default web design.

Run npm run build:watch to build the release in ./dist/ with regarding of changes in source files (js and scss, latter will be compiled to css). Open ./demo/index.html with any web browser. Reload page after changes are made (no auto reload yet).

npm scripts

script effect
npm run build delete old release and build new dev release in ./dist/
npm run build:watch delete old release and build new dev release in ./dist/, watches the filesystem for changes
npm run build:release delete old release and build new release in ./dist/, ready to publish
npm run deploy build release and publish to npmjs to org @arvato-crm, afterwards increment build number

Library for Microsoft Bot Framework Web Chat

There are three ways to include Microsoft Bot Framework Web Chat into this npm package:

  • use Microsoft Bot Framework Web Chat npm package botframework-webchat
    • import via import * as BotChat from 'botframework-webchat/botchat.js; and import 'botframework-webchat/botchat.css'; in index.js
    • HINT: framework version should be set to a fixed value in package.json!
    • !!! THIS IS HOW IT IS CURRENTLY DONE !!!
  • use prebuilt library from github release page https://github.com/Microsoft/BotFramework-WebChat/releases and place it in ./lib/ folder
    • import via import * as BotChat from '../lib/botchat.js'; and import '../lib/botchat.css'; in index.js
  • clone repo from github https://github.com/Microsoft/BotFramework-WebChat.git, use instructions to build a botframework-webchat release (https://github.com/Microsoft/BotFramework-WebChat, chapter Building Web Chat) and place the release files in ./lib/ folder
    • import via import * as BotChat from '../lib/botchat.js'; and import '../lib/botchat.css'; in index.js

Folders and files

Dev files in ./src/

  • ACAI.js - code to provide ACAI-JS-module
  • ChatWidget.js - module to start BotChat
  • acai-chatwidget.ejs - html template to embedd in given DOM element

Ressource files in ./res/

  • bot.svg, bot-bubble.svg - icons for chat bubble and sidebar title
  • acai-chatwidget.scss - styling for chat bubble and style override for CSS of Microsoft Bot Framework Web Chat

Library files in ./lib/

  • botchat.js, botchat.css - code from Microsoft Bot Framework Web Chat, downloaded from github oder built from github code via npm

Release in ./dist/

  • release files (built with npm run build[:watch|:release])
    • to include in HTML (when used without wepback/npm)
    • to publish to NPM

Demo in ./demo/

  • index.html - open in browser, see chapter on-the-fly development