@auroraai-bot-platform/rasa-webchat
v0.6.6
Published
Chat web widget for React apps and Rasa Core chatbots
Downloads
15
Maintainers
Readme
AURORAAI-BOT-PLATFORM/RASA-WEBCHAT
Customization
- Logo needs to be dimensioned 24px * 24px
- The logo should be an SVG, which has the fill color not set or set to currentColor, to enable coloring via the font color of the parent element
Integration
Integration can be done via releasing an npm package or direct download of the index.js file
Install
- install nodejs
- clone this repository
- run
npm ci
to install the dependencies
Run locally for testing or development
- run
npm run dev
Release
- run
npm run build
to make a release build - the build is in
lib/index.js
Official documentation
Features
- Text Messages
- Quick Replies
- Images
- Carousels
- Markdown support
- Persistent sessions
- Typing indications
- Smart delay between messages
- Easy to import in a script tag or as a React Component
🔥 Promo: check out our other cool open source project
Usage
In a <script>
tag
In your <body/>
:
<script>
!(function () {
let e = document.createElement('script'),
t = document.head || document.getElementsByTagName('head')[0];
(e.src =
'https://cdn.jsdelivr.net/npm/@auroraai-bot-platform/rasa-webchat@latest/lib/index.js'),
// For specific version use 'https://cdn.jsdelivr.net/npm/@auroraai-bot-platform/[email protected]/lib/index.js' where replace the 'x.x.x' with the version that you want
(e.async = !0),
(e.onload = () => {
window.WebChat.default(
{
customData: { language: 'en' },
socketUrl: 'https://bf-botfront.development.agents.botfront.cloud',
profileAvatar: 'AVATARPATH',
accentColor: 'COLORCODE',
accentDarkColor: 'COLORCODE',
languageList: {},
// add other props here
},
null
);
}),
t.insertBefore(e, t.firstChild);
})();
</script>
⚠️ Leave the version tag as 'latest' if you always want the latest version of the auroraai-bot-platform/rasa-webchat. But if you want to control when to update the widget, we recommend adding a version tag, e.g for version 1.0.0 'https://cdn.jsdelivr.net/npm/@auroraai-bot-platform/[email protected]/lib/index.js' The available versions of the auroraai-bot-platform/rasa-webchat can be seen in https://www.npmjs.com/package/@auroraai-bot-platform/rasa-webchat?activeTab=versions.
About images: width
and height
define the size in pixels that images in messages are crop-scaled to. If not present, the image will scale to the maximum width of the container and the image.
As a React component
Install the auroraai-bot-platform/rasa-webchat npm package
npm install @auroraai-bot-platform/rasa-webchat
and to install a specific package version add '@' and version number to the end of the url
npm install @auroraai-bot-platform/[email protected]
Then:
import Widget from '@auroraai-bot-platform/rasa-webchat';
function CustomWidget = () => {
return (
<Widget
initPayload={"/get_started"}
socketUrl={"http://localhost:5500"}
socketPath={"/socket.io/"}
customData={{"language": "en"}} // arbitrary custom data. Stay minimal as this will be added to the socket
title={"Title"}
subtitle=""
languageList={}
/>
)
}
Parameters
| Prop / Param | Default value | Description |
| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| initPayload
| null
| Payload sent to Rasa when conversation starts |
| socketUrl
| null
| Socket URL |
| socketPath
| null
| Close the chat window |
| customData
| null
| Arbitrary object sent with the socket. If using with Botfront, it must include the language (e.g. {"language": "en"}
) |
| docViewer
| false
| If you add this prop to the component or to the init script, docViewer=true
, this will treat links in received messages as links to a document ( .pdf .doc .xlsx
etc. ) and will open them in a popup using https://docs.google.com/viewer
service |
| title
| 'Welcome"
| Title shown in the header of the widget |
| subtitle
| null
| Subtitle shown under the title in the header of the widget |
| inputTextFieldHint
| "Type a message"
| User message input field placeholder |
| hideWhenNotConnected
| true
| If true
the widget will hide when the connection to the socket is lost |
| connectOn
| "mount"
| This prop lets you choose when the widget will try connecting to the server. By default, it tries connecting as soon as it mounts. If you select connectOn='open'
it will only attempt connection when the widget is opened. it can only take the values mount
and open
. |
| onSocketEvent
| null
| call custom code on a specific socket event |
| embedded
| false
| Set to true
if you want to embed the in a web page. The widget will always be open and the initPayload
will be triggered immediately |
| showFullScreenButton
| false
| Show a full screen toggle |
| displayUnreadCount
| false
| Path to an image displayed on the launcher when the widget is closed |
| showMessageDate
| false
| Show message date. Can be overriden with a function: (timestamp, message) => return 'my custom date'
|
| customMessageDelay
| See below | This prop is a function, the function take a message string as an argument. The defined function will be called everytime a message is received and the returned value will be used as a milliseconds delay before displaying a new message. |
| params
| See below | Essentially used to customize the image size, also used to change storage options. |
| storage
| "local"
| ⚠️ This is not a prop, it has to be passed inside the params object above. Specifies the storage location of the conversation state in the browser. "session"
defines the state to be stored in the session storage. The session storage persists on reload of the page, and is cleared after the browser or tab is closed, or when sessionStorage.clear()
is called. "local"
defines the state to be stored in the local stoage. The local storage persists after the the browser is closed, and is cleared when the cookies of the browser are cleared, or when localStorage.clear()
is called. |
| customComponent
| null
| Custom component to be used with custom responses. E.g.: customComponent={ (messageData) => (<div>Custom React component</div>)}
. Please note that this can only be used if you call the webchat from a React application as you can't write a component in pure Javscript. |
| onWidgetEvent
| {}
| call custom code on a specific widget event ( onChatOpen
, onChatClose
, onChatHidden
, are available for now ), add a function to the desired object property in the props to have it react to the event. |
| showMenuButton
| true
| Show menu button in the header bar |
| languageList
| {}
| Has the list of languages the webchat supports. The languages are shown in the menu view where the user can change them. The languageList needs to have the languages listed in a list, for example: '{ en: 'English', fi: 'Suomi', sv: 'Svensk' }'. The language needs to have the 2 letter ISO 639-1 standard country code and a name of the language, that will be shown in the webchat. |
| automaticLanguageChange
| true
| Can be used to disable the automatic language change. By default this feature is on. When web page is refreshed, the webchats language is changed automatically to the web pages language (the language that is in the pages HTML element). The language is changed only if the page language exists in the languageList parameter. This makes sure that the webchat language is not changed to an unsupported language. Also the language is changed only if the user hasn't written anything to the chat, meaning that the conversation hasn't started. If the conversation is ongoing, the language is not changed automatically. |
Additional Examples
customMessageDelay
(message) => {
let delay = message.length * 30;
if (delay > 2 * 1000) delay = 3 * 1000;
if (delay < 400) delay = 1000;
return delay;
};
onSocketEvent
onSocketEvent={{
'bot_uttered': () => console.log('the bot said something'),
'connect': () => console.log('connection established'),
'disconnect': () => doSomeCleanup(),
}}
params
The params
props only allows to specify custom image dimensions:
params={{images: { dims: { width: 300, height: 200 }}}}
Other features
Setting of languages
The default language used in the webchat can be set with the CustomData parameter 'language' value.
customData={{"language": "en"}}
or if the package is loaded using a script:
customData = { language: 'en' };
- If the language is not set in CustomData parameter, the default language of the Botfront is then used.
- If the Botfront doesn't have a default language, english ('en') will be used.
The language options that the webchat supports needs to be listed in the 'languageList' parameter. These languages will be listen in the webchat menu view that the chat user can open, and change the used language from there.
languageList={{ en: "English", sv: "Svensk" }}
or if the package is loaded using a script
languageList: { en: 'English', sv: 'Svensk' };
The language translations of texts used in the webchat are added to the 'i18n/i18n.js' file.
The automatic language change feature is active by default. When web page is refreshed, the webchats language is changed automatically to the web pages language (the language that is in the pages HTML element). The language is changed only if:
- The page language exists in the languageList parameter. This makes sure that the webchat language is not changed to an unsupported language.
- The language is changed only if the user hasn't written anything to the chat, meaning that the conversation hasn't started. If the conversation is ongoing, the language is not changed automatically.
The automatic language change feature can be disabled by setting the parameter 'automaticLanguageChange' to false.
Tooltips
Text messages received when the widget is closed will be shown as a tooltip.
Sending a message on page load
When reconnecting to an existing chat session, the bot will send a message contained in the localStorage key specified by the NEXT_MESSAGE
constant. The message should be stringified JSON with a message
property describing the message and an expiry
property set to a UNIX timestamp in milliseconds after which this message should not be sent. This is useful if you would like your bot to be able to offer your user to navigate around the site.
Sending a payload from your React app
function myComponent() {
const webchatRef = useRef(null);
// triggered when something happens in your app
function callback() {
if (webchatRef.current && webchatRef.current.sendMessage) {
webchatRef.current.sendMessage('/myIntent{"entityName":"value"}');
}
}
return <RasaWebchat ref={webchatRef} />;
}
The payload can be any message that the user would normally send, but if you want to force an intent and maybe some entities, you can use that format
/myIntent{"entity1":"value1","entity2":"value2"}
Backends
The widget can be used with any backend but is primarily designed to be used with Rasa or Botfront.
Rasa
Use the socketio
channel: See instructions in the Rasa documentation
If you want to process customData
in Rasa you have to create a new channel. Use channel rasa_core.channels.socketio
as a template for your new channel. In this channel, customData
can be retrieved via data['customData']
. Then you can modify sender_id
, save customData
to the database, fill slots or whatever you need to with your additional data.
Botfront
The Rasa Webchat is developped by the Botfront team and it works with Botfront. If your bot is multilingual, make sure to specificy the current language in the customData
prop. E.g. customData={{language: 'en'}}
. See in Botfront docs for more details.
Styles
From version 0.8 we started prefixing all css classes, if you already had css styling for the widget, just prepend rw-
to all the classes you changed.
hierarchy:
.rw-conversation-container
|-- .rw-header
|-- .rw-title
|-- .rw-close-function
|-- .rw-loading
|-- .rw-messages-container
|-- .rw-message
|-- .rw-client
|-- .rw-response
|-- .rw-replies
|-- .rw-reply
|-- .rw-response
|-- .rw-snippet
|-- .rw-snippet-title
|-- .rw-snippet-details
|-- .rw-link
|-- .rw-imageFrame
|-- .rw-videoFrame
|-- .rw-sender
|-- .rw-new-message
|-- .rw-send
| Class | Description | | -------------------------- | ------------------------------------------------------------------ | | .rw-widget-container | The div containing the chatbox of the default version | | .rw-widget-embedded | div of the embedded chatbox (using embedded prop) | | .rw-full-screen | div of the fullscreen chatbox (using fullScreenMode prop) | | .rw-conversation-container | the parent div containing the header, message-container and sender | | .rw-messages-container | the central area where the messages appear | | .rw-sender | div of the bottom area which prompts user input | | .rw-new-message | the text input element of sender | | .rw-send | the send icon element of sender | | .rw-header | div of the top area with the chatbox header | | .rw-title | the title element of the header | | .rw-close-button | the close icon of the header | | .rw-loading | the loading status element of the header | | .rw-message | the boxes holding the messages of client and response | | .rw-replies | the area that gives quick reply options | | .rw-snippet | a component for describing links | | .rw-imageFrame | a container for sending images | | .rw-videoFrame | a container for sending video |
Original Rasa-webchat contributors
@PHLF @znat @TheoTomalty @Hub4IT @dliuproduction @MatthieuJnon @mofortin @GuillaumeTech
Copyright (C) 2021 Dialogue Technologies Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.(C) 2021 Dialogue Technologies Inc. All rights reserved.