It is possible to embed webchat on almost any page and it requires only a few steps.

Newest Versions:

chat-ui - 234
chat-ui-launcher - 1.52.2

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.52.2.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.52.2.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.52.2.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.52.2.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.52.2.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.52.2.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.52.2.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, },`or `autoStart: 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 },` or `silenceMessage: 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)

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'); }`

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

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).

More info:

Release note: https://automate.help.sentione.com/docs/v221
About functionality: https://automate.help.sentione.com/docs/blocking-operations