How to embed webchat on page - Configuration
It is possible to embed webchat on almost any page and it requires only a few steps.
Newest Versions:
- chat-ui -
205
- chat-ui-launcher -
1.32.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.32.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.30.2.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.tst-stage.chatbots.senti.one/fullscreen',
projectId: '78590208-3483-407b-9b8c-70e9aabd1828'
})
</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.32.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.tst-stage.chatbots.senti.one/fullscreen',
projectId: '78590208-3483-407b-9b8c-70e9aabd1828',
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.32.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.tst-stage.chatbots.senti.one/fullscreen',
projectId: '78590208-3483-407b-9b8c-70e9aabd1828',
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.32.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.tst-stage.chatbots.senti.one/fullscreen',
projectId: '78590208-3483-407b-9b8c-70e9aabd1828',
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.32.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.tst-stage.chatbots.senti.one/fullscreen',
projectId: '78590208-3483-407b-9b8c-70e9aabd1828',
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.32.0.js" type="application/javascript"></script>
<script>
window.sentiOneChat.initWebChat({
chatSrc: 'https://webchat.tst-stage.chatbots.senti.one/fullscreen',
projectId: '78590208-3483-407b-9b8c-70e9aabd1828',
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.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.text | string | Initial message that will be sent to bot to start conversation | text: Say hello" |
initialMessage.extraData | object | Initial extraData that will be sent to bot to start conversation | extraData: { process: "process_name" } |
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.text | string | Message that will be send to bot while user is not responding | `silenceMessage: { delayTime: 2000, text: "", } ```` |
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 } |
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' |
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; |
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 | |
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 |
Updated 17 days ago