Web Widget

Introduction

To make it as easy as possible for you, to add a BotMan powered chatbot into your website, BotMan ships with a custom chat widget that you can use out of the box. It uses Preact under the hood, which results in a minimal footprint of only 5kb (gzipped).

The web widget currently supports buttons, texts, images, videos, audio responses and the Facebook list- and button-template, so that you can just use the web widget, without modifying the code - even if it is specific to a messenger service.

You can also see it running here in the documentation - most of the code samples work with the web driver, so feel free to just give it a try!

Requirements & Building

Install nodejs

apt-get install build-essential libssl-dev
apt-get install nodejs
nodejs -v
apt-get install npm
npm -v

Install nvm

To download the nvm installation script from the project's GitHub page, you can use curl. Note that the version number may differ from what is highlighted here:

curl -sL https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh -o install_nvm.sh

Inspect the installation script with nano:

nano install_nvm.sh

Run the script with bash:

bash install_nvm.sh

It will install the software into a subdirectory of your home directory at ~/.nvm. It will also add the necessary lines to your ~/.profile file to use the file.

To gain access to the nvm functionality, you'll need to either log out and log back in again or source the ~/.profile file so that your current session knows about the changes:

source ~/.profile

With nvm installed, you can install isolated Node.js versions. For information about the versions of Node.js that are available, type:

nvm ls-remote

Then you can use nvm to install the node version you need

nvm use <version>

On Mac via homebrew:

brew install npm
brew install nvm

Build the widget

cd <path_to_widget>
npm install -g grunt-cli
npm install -g webpack
npm install -g bower
npm install -g gulp
npm install preact
npm install
npm run-script build

Installation & Setup

The BotMan Web Widget is a frontend widget to use in combination with the Web Driver. Make sure you install the web driver first, before you add the web widget to your website.

Usage with BotMan Studio

If you use BotMan Studio - using the web widget could not be simpler. It already includes the web driver which comes with a view and route to use in combination with the web widget. Simply add the Javascript snippet to your website:

<script src='https://cdn.jsdelivr.net/npm/botman-web-widget@0/build/js/widget.js'></script>

That's it. You will now see a message icon in the bottom right corner. When you click it, it will open the chat widget.

{callout-info} The script is now loading the chat iFrame from the botman/chat endpoint, which is automatically being added by the web-driver.

Usage without BotMan Studio

If you are not using BotMan Studio and want to make use of the BotMan web widget, there are 2 steps involved.

Chat Frame

When you open the web widget, it will load an iframe containing the chat area. In order to load this iframe, create a URL / route that is accessible from your application and contains the chat frame sourcecode:

<!doctype html>
<html>
<head>
    <title>BotMan Widget</title>
    <meta charset="UTF-8">
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/botman-web-widget@0/build/assets/css/chat.min.css">
</head>
<body>
<script id="botmanWidget" src='https://cdn.jsdelivr.net/npm/botman-web-widget@0/build/js/chat.js'></script>
</body>
</html>

Widget

Next you need to add the widget to your website and tell it to use the chat frame URL that you just created. Simply add the Javascript to your website and configure it using a global config object. Place the URL that you created for the chat frame in the frameEndpoint configuration key.

<script>
var botmanWidget = {
    frameEndpoint: '/iFrameUrl'    
};
</script>
<script src='https://cdn.jsdelivr.net/npm/botman-web-widget@0/build/js/widget.js'></script>

Configuration & Customization

When adding the widget to your own website, you probably want to customize the look of the widget, the title that get's displayed in the widget bar, background images etc. That's why the web widget comes with a detailed set of configuration options.

To apply these options to your widget, just declare an option called botmanWidget before loading the widget's Javascript.

The UI of the chat widget itself can simply be customized via CSS - take a look at the default CSS to see the available selectors.

Available settings

Key Default Description
chatServer
/botman
The URL of the BotMan route / server to use.
frameEndpoint
/botman/chat
The location of your chat frame URL / route.
timeFormat
HH:MM
Time format to use
dateTimeFormat
m/d/yy HH:MM
Date-Time format to use
title
BotMan Widget
The title to use in the widget.
introMessage
null
This is a welcome message that every new user sees when the widget is opened for the first time.
placeholderText
Send a message...
Input placeholder text
displayMessageTime
true
Determine if message times should be shown
mainColor
#408591
The main color used in the widget header.
bubbleBackground
#408591
The color to use for the bubble background.
bubbleAvatarUrl

        
The image url to use in the chat bubble.
desktopHeight
450
Height of the opened chat widget on desktops.
desktopWidth
370
Width of the opened chat widget on desktops.
mobileHeight
100%
Height of the opened chat widget on mobile.
mobileWidth
300
Width of the opened chat widget on mobile.
videoHeight
160
Height to use for embedded videos.
aboutLink
https://botman.io
Link used for the "about" section in the widget footer.
aboutText
Powered by BotMan
Text used for the "about" section in the widget footer.
userId

        
Optional user-id that get's sent to BotMan. If no ID is given, a random id will be generated on each page-view.

API

The web widget also comes with an API to programatically send messages from the user or chatbot. You might use this feature when the user clicks on a button on your website to instantly trigger the chatbot, without having the user to type something. Once the chat widget is initialized, you can access it's API on the botmanChatWidget object that get's exposed to the window containing the chat widget.

Available Methods

Method Description
botmanChatWidget.open()
Open the chat widget. Try out
botmanChatWidget.close()
Close the chat widget. Try out
botmanChatWidget.toggle()
Toggle the chat widget. Try out
botmanChatWidget.say(text)
Say something on behalf of the user.
The given text is visible in the widget.
Try out
botmanChatWidget.whisper(text)
Similar to say, with the difference that the text is not visible. Try out
botmanChatWidget.sayAsBot(text)
Say something on behalf of the chatbot.
The text is visible in the widget.
Try out