A BotMan frontend package for the web widget
npm install botman-extended-web-widget
Integrate a rich chatbot experience into your website
> - Overview
> - Demo
> - Features
> - Installation
> - Usage
> - Configuration
> - Customization
> - Contributing
> - Acknowledgments
> - Supporting
> - License
---
The BotMan Extended Web Widget is an enhanced version of the BotMan Web Widget that allows you to integrate a rich chatbot experience into your website. The widget is built using modern web technologies and provides a seamless integration experience. It offers features such as shadow DOM, custom styles injection, enhanced authentication, and support for single-page application (SPA) frameworks.
---
- HTML Implementation: Check out this HTML Example
- VUE SPA Implementation: Check out this Vue SPA Example
- No Iframe Required: Leverage modern web technologies to embed your chatbot.
- Shadow DOM: Utilize encapsulated styles and markup for widget isolation.
- Custom Styles Injection: Easily apply custom styles to match your website's theme.
- Enhanced Authentication: Secure your chatbot with custom headers.
- Vite and TypeScript: optimized build process and improved code reliability.
- SPA Framework Support: Seamlessly integrate the widget into your React, Angular, or Vue app.
---
npm
``bash
npm install botman-extended-web-widget
``
yarnbash`
yarn add botman-extended-web-widget
javascript
import BotManWidget from 'botman-extended-web-widget';
new BotManWidget({
chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
});
`
$3
in your HTML file, add the following code:`html
BotMan Widget
`
$3
`javascript
import BotManWidget from 'botman-extended-web-widget';new BotManWidget({
chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
frameEndpoint: './chat.html',
useChatAsIframe: true,
useInAppCss: false,
useShadowDom: false,
useLoader: true,
requestHeaders: {
'X-Shop-Domain': '1234'
},
customStylesInjection:
/ with iframe /
html, body{
background-color: red;
}
,`
});Configuration
The BotMan Extended Web Widget can be configured using the following options:
Orginal options can be found here
Here are the new options:
| Option | Type | Description | default | notes |
| --- | --- | --- | --- | --- |
| useChatAsIframe | boolean | Whether to use the chat as an iframe. | false |
| useInAppCss | boolean | Whether to use in-app inline CSS. | false |
| useShadowDom | boolean | Whether to use shadow DOM. | true | css is always injected |
| requestHeaders | object | Custom headers for authentication. | {} |
| customStylesInjection | string | Custom styles to inject into the widget. | '' |
| autoInit | boolean | Whether to automatically initialize the widget. use if load in html | false |
| useLoader | boolean | Whether to use a loader as a type indication until the server responds | false |
| sandboxAttributes | string | The sandbox attribute for the iframe | '' | Sandbox Docs |
javascript
var wasChatOpened = false; // Flag to track if the chat was opened
window.addEventListener('chatOpenStateChange', function(event) {
// event.detail = {isOpen: true} or {isOpen: false}
if (event.detail.isOpen && !wasChatOpened) {
// This block will only execute once, the first time the chat is opened
window.botmanChatWidget.whisper("start conversation");
wasChatOpened = true; // Set the flag to true after sending the message
}
});
`
Customization
$3
The BotMan Extended Web Widget can be customized using the customStylesInjection option. This option accepts a string containing CSS rules that will be injected into the widget. The following example demonstrates how to customize the widget's appearance:`javascript
new BotManWidget({
chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
frameEndpoint: './chat.html',
useChatAsIframe: true,
useInAppCss: false,
useShadowDom: false,
requestHeaders: {
'X-Custom-Header': '1234'
},
customStylesInjection: / with iframe /
html, body{
background-color: red;
}
,`
});customStylesInjection$3
To embed a custom background image to the chat window, you can use the option to set the background-image property. The following example demonstrates how to add a background image to the chat window with vite speciel syntax:
`javascript
import svgContent from '../assets/chat-background.svg?raw';
const encodedSvg = encodeURIComponent(svgContent);
new BotmanWidget({
customStylesInjection:
.botmanWidgetRootInner > div:nth-child(2) {
background-image: url("data:image/svg+xml,${encodedSvg}");
}
,`
});
option to set the isActionRespondVisible parameter to true. The following example demonstrates how to add buttons to the chat window:`php
public function startConversation()
{
$question = Question::create('Do you need support or help with anything?')
->fallback('Unable to ask question')
->callbackId('ask_support')
->addButtons([
Button::create('Yes, I need help')->value('yes')->additionalParameters(['isActionRespondVisible' => true]),
Button::create('No, thank you')->value('no')->additionalParameters(['isActionRespondVisible' => true]),
]);
}
``- BotMan - The original BotMan Web Widget provided the foundation for the BotMan Extended Web Widget. This project builds upon the original by adding new features and enhancements while maintaining compatibility with existing BotMan infrastructure. Thanks to Marcel Pociot, the creator of BotMan.