Configuration
New improved support for webchat is available!
Singe version v234 there is completely new way to configure webchat on You website. You can now configure it through Channels module through UI!
This document shows legacy way to embed webchats on HTML websites
Please note that since version v234 configuring webchat like stated below is not recommended and may be disabled in the future. Please migrate to configuration through Channels module.
It is possible to embed webchat on almost any page and it requires only a few steps.
Newest Versions:
- chat-ui -
240 - chat-ui-launcher -
1.54.0
Load setting up script
Necessary step. You need to add the following line to the root HTML file of your app (location of root HTML file may vary based on the technology of your webapp).
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js"></script>
X - the version of the script to configure the chat depends on the environment version.
This page always describe the newest version of webchat. In case you would like to see changelog of webchat click here:
Initialize and run webchat
After the script is loaded, your window object will have a sentiOneChat property. This is the main object used to initialize and manipulate webchat from within the host page.
<script>
window.sentiOneChat.initWebChat(Configuration object - read below);
</script>
Examples
Minimal configuration
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.app.chatbots.sentione.com/fullscreen',
projectId: '6897f1fc-8106-4f6e-845e-9303249edbda'
})
</script>
</head>
<body>
<h1>Your webchat is ready to use!</h1>
</body>
</html>
Playground: https://jsfiddle.net/dnr6tyhk/
Automatically opening webchat after one second
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.app.chatbots.sentione.com/fullscreen',
projectId: '6897f1fc-8106-4f6e-845e-9303249edbda',
autoStart: 1000
})
</script>
</head>
<body>
<h1>Your webchat is ready to use!</h1>
</body>
</html>
Set custom header title and input placeholder
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.app.chatbots.sentione.com/fullscreen',
projectId: '6897f1fc-8106-4f6e-845e-9303249edbda',
appearance: {
inputPlaceholder: "Type your message here...",
headerTitle: "Awesome webchat!"
}
})
</script>
</head>
<body>
<h1>Your webchat is ready to use!</h1>
</body>
</html>
Styling webchat
There is a possibility to set custom styles of webchat. You should use this method (field: appearance.styels to style inner elements of webchat and webchat trigger button).
You can do it in two ways:
- provide custom CSS styles:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.app.chatbots.sentione.com/fullscreen',
projectId: '6897f1fc-8106-4f6e-845e-9303249edbda',
appearance: {
styles: {
customCss: '.chat-header { background-color: red;}'
}
}
})
</script>
</head>
<body>
<h1>Your webchat is ready to use!</h1>
</body>
</html>
- provide link to external stylesheet
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.app.chatbots.sentione.com/fullscreen',
projectId: '6897f1fc-8106-4f6e-845e-9303249edbda',
appearance: {
styles: {
url: 'https://cdn.sentione.com/chat-ui-launcher/themes/dark-blue.css'
}
}
})
</script>
</head>
<body>
<h1>Your webchat is ready to use!</h1>
</body>
</html>
Change default position of webchat
Provided styles to this field (appearance.outerStyles) will be injected to host page. So you should use this field if you want to style position of webchat.
You can provide custom CSS or link to stylesheet. In below example you can see customCss to set webchat position with 500px right margin.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
<script src="https://cdn.sentione.com/chat-ui-launcher/chat.1.54.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.app.chatbots.sentione.com/fullscreen',
projectId: '6897f1fc-8106-4f6e-845e-9303249edbda',
appearance: {
outerStyles: {
customCss: '.socui-chat__button-iframe {right: 500px} .socui-chat__window {right: 500px}'
}
}
})
</script>
</head>
<body>
<h1>Your webchat is ready to use!</h1>
</body>
</html>
Configuration object
| Field name (* - required) | Type | Description | Example value |
|---|---|---|---|
| chatSrc * | string | URL: https://webchat.app.chatbots.sentione.com/fullscreen. This address should be changed for on-premise deployments | https://webchat.app.chatbots.sentione.com/fullscreen |
| projectId * | string | Project id | |
| author | string | Name of the user, this value will be visible in Conversation analytics | |
| sourceType | string | Field to mark conversation with custom source name. Value will be visible in conversation analytics | |
| appearance | object | Object to set up appearance of the webchat | ``` appearance: { headerTitle: "Sentione chat", avatar: { src: 'https://cdn.sentione.com/chat-ui-launcher/avatars/avatar-male.png ', showNearBubble: true, showInHeader: false, }, }, ``` |
| appearance.avatar | object | Object to config avatar | ```avatar: { src: 'https://cdn.sentione.com/chat-ui-launcher/avatars/avatar-male.png ', showNearBubble: true, showInHeader: false, }, ``` |
| appearance.avatar.src | appearance.avatar.src | Url to custom avatar | |
| appearance.avatar.showNearBubble | boolean | Display setting of the avatar near to message bubble | |
| appearance.avatar.showInHeader | boolean | Display setting of the avatar in chat header | |
| appearance.icons | object | ||
| appearance.icons.openButtonIcon | string | URL to icon which will be displayed as open conversation window button | |
| appearance.icons.minimizeButtonIcon | string | URL to icon which will be displayed as minimize conversation window button | |
| appearance.icons.closeButtonIcon | string | URL to icon which will be displayed as close and reset conversation window button | |
| appearance.icons.activeSendMessageButtonIcon | string | URL to icon which will be displayed as send message button (active) | |
| appearance.icons.disabledSendMessageButtonIcon | string | URL to icon which will be displayed as send message button (disabled - not active) | |
| appearance.icons.autoScrollToBottomIcon | string | URL to icon which will be displayed as scroll to bottom button | |
| appearance.styles | object | Object to setup custom styles of webchat (how webchat will looks like inside) | ````styles: { url: '<https://cdn.sentione.com/chat-ui-launcher/themes/dark-blue.css> ', themeColor: 'red' }``` ```` |
| appearance.styles.url | string | Url to custom stylesheet | ````styles: { url: '<https://cdn.sentione.com/chat-ui-launcher/themes/dark-blue.css> ', }``` ```` |
| appearance.styles.customCss | string | Custom css rules | styles: { customCss: '.chat-header__title {color: red;}', } |
| appearance.styles.themeColor | string | Main color of webchat | styles: { themeColor: 'red', } |
| appearance.outerStyles | object | Object to setup mostly position of webchat on host page. These styles will be injected to host page | |
| appearance.outerStyles.url | string | Url to custom stylesheet | |
| appearance.outerStyles.customCss | string | Custom css rules | |
| appearance.headerTitle | string | User will see it in header | ```headerTitle: "Sentione chat", ``` |
| appearance.endOfConversationLabel | string | User will see this label as end of conversation message | |
| appearance.startNewConversationButtonLabel | string | User will see this label in button to start new conversation | |
| appearance.conversationWindowWidth | string | Field to set up width of the conversation window | {conversationWindowWidth: '300px'} |
| appearance.conversationWindowHeight | string | Field to set up height of the converstion window | {conversationWindowHeight: '300px'} |
| appearance.inputPlaceholder | string | Placeholder of the input | |
| autoStart | object or number | Field to setup auto open chat behavior. - no field or -1 - chat will stay closed until user click to open manually - 0 - chat will open automatically - above 0 - chat will open after defined time | `autoStart: { delayTime: 2000, },orautoStart: 2000```` |
| autoStart.delayTime | number | Time to delay automatically open chat | autoStart: 2000 |
| initialMessage | object | Object to set up initial message. Thanks to it, bot can start from specific block | `initialMessage: { text: "", extraData: { process: "process_name" }, }, ```` |
| initialMessage.extraData | object | Initial extraData that will be sent to bot to start conversation | extraData: { process: "process_name" } |
| initialMessage.delayTime | number | There is posibility to start conversation automatically (send initialMessage) even if conversation window is closed without opening. Available from v234 For example delayTime = 2000 and auto open is disabled, webchat after 2s will send initial message with extradata to API, without opening webchat. When user decide to open conversation window, will see already started conversation. If this setting is enabled, after each page refresh, webchat will send initialMessage after specified time so consider using this option with conversationHistory setting (read more below) to avoid to many messages from bot in conversation window. | |
| conversationHistory | 'load' | 'abandon' | 'no-load' | Setting to provide what webchat should do with conversation history. Load - conversation history will be loaded (default behaviour) Abandod - previous conversation will be abandoned No-load - previous conversation will be continued but without loading conversatio history | |
| silenceMessage | object or number | Option to setup behaviour to handle missing message from a user | `silenceMessage: { delayTime: 2000 }, orsilenceMessage: 2000```` |
| silenceMessage.delayTime | number | Delay value to send message while user is not responding | silenceMessage: { delayTime: 2000 } |
| silenceMessage.extraData | object | Object that will be send to bot while user is not responding | `silenceMessage: { delayTime: 2000, text: "", extraData: {"process:" :"X"} }```` |
| silenceMessage.maxRepetition | number | Value to specify how many silence message webchat should send in one conversation turn. For example with setting maxRepetition = 1, webchat will send only one silence message in one conversation turn. Remember that delayTime and (one of) extraData or text is required to turn on silence message mechanism. Field available from version 214 | silenceMessage: { delayTime: 2000, extraData: {"process:" :"X"}, maxRepetition: 1 } |
| everyMessage | object | ||
| everyMessage.extraData | object | Field to pass extraData object with every message from user to bot. If extraData from silenceMessage or initialMessage is used, object will be merged, and more specific (silenceMessage and initialMessage) will overwrite the same keys in object | |
| actionButtons | object | Object to define which action buttons should be visible | `actionButtons: { conversationWindow: { minimize: true }, }```` |
| actionButtons.conversationWindow.minimize | boolean | Show or hide button to minimize conversation window | `actionButtons: { conversationWindow: { minimize: true }, }```` |
| actionButtons.conversationWindow.resetAndMinimize | boolean | Show or hide button to reset (clear) conversation and minimize conversation window | `actionButtons: { conversationWindow: { resetAndMinimize: true }, }```` |
| language | string ('en' | 'pl') | Language to use by default, this is mostly important when errors occur (for example message can't be sent) | 'en' |
| scrollOptions | object | ||
| scrollOptions.scrollTo | string ('topOfMessage' or 'bottom') | The scroll behavior control option provides users with the ability to determine how the WebChat interface responds when encountering lengthy messages. Traditionally, the conversation window would scroll automatically to the bottom, displaying the latest message at the bottom of the visible area. However, with this new feature, users can now modify this behavior based on their preference. When the option is set to "Scroll to Top," the WebChat interface will intelligently scroll upwards to display the beginning of the lengthy message at the top of the conversation window. This is particularly useful when users want to read the entire message from the beginning, ensuring they don't miss any crucial details. By having the message displayed at the top, users can easily review the content without the need to manually scroll upwards. On the other hand, when the option is set to "Scroll to Bottom" (the default behavior), the conversation window will continue to scroll automatically to the bottom, displaying the latest message at the bottommost visible area. This behavior is suitable for users who prefer to focus on the most recent message without interruptions, allowing them to keep up with the ongoing conversation seamlessly. The new scroll behavior control option can be easily accessed and modified within the WebChat configuration settings. | |
| session | object | ||
| session.hostSessionCookie | boolean | To enable conversation session cookie managed by frontend (better support by browsers like Safari) | |
| announcementBanner (from v246) | object | The Announcement Banner feature provides a customizable topbar in the web chat interface. It can be configured to display important messages or announcements with options for markdown content, link behaviors, and dismissible actions. | |
| announcementBanner.content | string | Required. The text or markdown content to display in the banner. | |
| announcementBanner.closable | boolean | Optional. If true, displays a close button for the banner. Default: true. | |
| announcementBanner.markdownLinkBehavior | 'new-tab' | 'callback' | Optional. Defines how markdown links behave. Default: 'new-tab'. | |
| announcementBanner.onlyOnce | boolean | Optional. If true, the banner is shown only once per conversation. Default: true. | |
| indicator | object | ||
| indicator.unreadMessages | object | ||
| indicator.unreadMessages.symbol | string | Symbol will be presented in Orange dot (color, size, can be changes via custom CSS). Can be empty, then orange dot will be empty. | |
| indicator.unreadMessages.delayTime | number | Duration in milliseconds for the 'orange dot' popup delay. (Default is 1000ms) | |
| indicator.encouragementMessage | object | ||
| indicator.encouragementMessage.text | string | The text provided will appear within a 'message bubble' and can be left empty. The maximum length allowed for the text is 300 characters | |
| indicator.encouragementMessage.delayTime | number | Duration in milliseconds for the 'message bubble' popup delay. (Default is 1000ms) | |
| onOpenChat | function | Callback function | `onOpenChat: () => { console.log('Chat is open'); }```` |
| onCloseChat | function | Callback function | `onCloseChat: () => { console.log('Chat is closed'); }```` |
| onInitializedChat | function | Callback function | `onInitializedChat: () => { console.log('Chat is initialized'); }```` |
| onOpeningButtonClick | function | Callback function | `onOpeningButtonClick: () => { console.log('User clicked to open chat'); }```` |
| onConversationEnd | function | Callback function | `onConversationEnd: () => { console.log('End of conversation'); }```` |
| onMinimizeConversationWindow | function | Callback function | `onMinimizeConversationWindow: () => { console.log('User minimized conversation window'); }```` |
| onCloseConversationWindow | function | Callback function | `onCloseConversationWindow: () => { console.log('User closed conversation window'); }```` |
| onMessageSent | function: (message: string) => void; | ||
| onMessageReceived | function: (response) => void; | ||
| onDestroyedChat | void | Callback method. Method is called after the webchat has been removed from a web page. This method can be used to perform any cleanup tasks that may be necessary after the webchat has been removed. | onDestroyedChat: () => { console.log('Chat destroyed an session is destroyed'); } |
| updateConfig | void | Method to update webchat configuration, without reloading webchat. |
sentiOneChat object available methods
On object window.sentiOneChat host page can call several methods to control state of webchat conversation window
Available methods:
| Field name (* - required) | Arguments | Return type | Description |
|---|---|---|---|
| isChatOpen() | boolean | Method to check if conversation window is opened or closed | |
| isChatInitialized() | boolean | Method to check if webchat is available and initialized on page or not | |
| initWebChat(configurationObject) | configurationObject - object | void | Method to initialize webchat component on page |
| open() | void | Method to open (show) chat conversation window. | |
| close() | void | Method to close conversation window and reset current conversation (it will also turn off silence Message functionality) | |
| minimize() | void | Method to close conversation window but without closing/resting current conversation (if silence message functionality is turned on, after receive new message from bot, conversation window will open automatically) | |
| destroy() | void | Method to remove at all webchat from page, and reset conversation session. To do an action after destroy, use onDestroyedChat() callback | |
| updateConfig | configurationObject | void | Method to update webchat configuration, without reloading webchat. Example:window.sentiOneChat.updateConfig({ everyMessage: { extraData: { token: 'new_token' } } })` |
| onAnnouncementBannerLinkClick | data | void | Triggered when a link in the banner is clicked |
| onAnnouncementBannerClose | data | void | Triggered when the banner is closed |
Post messages event types
You can send a specific postMessage event to webchat embedded in iframe.
When you use (embed) out webchat with out script chat-ui-launcher you don't need to work with postMessages on your own. Script is doing it for you. But you can embed our webchat in iframe wihtou chat-ui-launcher script, then you have to handle all communication on your own.
Example: https://jsfiddle.net/8c0asmeo/
Event format
Event has to be an JSON object
{
"type": "SET_CONFIG",
"payload": {
"projectId": "a4b5ec59-1875-45c8-8964-6fc2616cacdb",
"actionButtons":{
"conversationWindow": {"minimize": false}
}
}
}
Supported events by webchat:
| Event type name | Payload | payload details |
|---|---|---|
| SET_CONFIG | configuration Object | This is required event to set webchat ready to work. Read Configuration object chapter to get more info |
| START_CONVERSTAION | null | Required event to start conversation by webchat. This event should be send to send first message bot. |
| CLOSE_CONVERSATION | null | Event to close and reset conversation session and history. |
Events send by webchat to host page
| Event type name | Payload | Payload details |
|---|---|---|
| WEBCHAT_READY | null | Event is sent by webchat to host page after webchat initialization. |
| CLIENT_MESSAGE_SENT | message | Event is sent by webchat to host page after send message from user to bot |
| MESSAGE_RECEIVED | message | Event is sent by webchat to host page after webchat receive message from bot |
| CONVERSATION_END | null | Event is sent by webchat to host page after finish conversation. |
| CLOSE_CONVERSATION_WINDOW | null | Event is sent by webchat to host page after user click X icon from webchat's header |
| MINIMIZE_CONVERSATION_WINDOW | null | Event is sent by webchat to host page after user click MINIMIZE icon from webchat's header |
Supported Commands
- BlockingOperation - will block (hide) input during long operation (mostly integration).
- AnnouncementBanner - command allows dynamic control over the banner during a session. This is particularly useful for context-specific messages. Read more here
- Carousel - Carousel is an interactive element of the webchat interface that allows presentation of content in the form of a horizontal slider with multiple slides. Each slide can contain a title, text, graphics, and action buttons. Users can navigate between slides using buttons or touch gestures (swipe). Read more here
More info:
- Release note: https://automate.help.sentione.com/docs/v221
- About functionality: https://automate.help.sentione.com/docs/blocking-operations
Updated 2 months ago