Automate

Configuration

Suggest Edits

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

Newest Versions:

  • chat-ui - 228
  • chat-ui-launcher - 1.47.1

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.47.1.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.47.1.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.47.1.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.47.1.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.47.1.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.47.1.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.47.1.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)TypeDescriptionExample value
chatSrc *stringURL: https://webchat.app.chatbots.sentione.com/fullscreen.

This address should be changed for on-premise deployments		https://webchat.app.chatbots.sentione.com/fullscreen
projectId *stringProject id
authorstringName of the user, this value will be visible in Conversation analytics
sourceTypestringField to mark conversation with custom source name. Value will be visible in conversation analytics
appearance objectObject 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 objectObject to config avatar```avatar: {
src: 'https://cdn.sentione.com/chat-ui-launcher/avatars/avatar-male.png

',
showNearBubble: true,
showInHeader: false,
},
```
appearance.avatar.srcappearance.avatar.srcUrl to custom avatar
appearance.avatar.showNearBubblebooleanDisplay setting of the avatar near to message bubble
appearance.avatar.showInHeaderbooleanDisplay setting of the avatar in chat header
appearance.iconsobject
appearance.icons.openButtonIconstringURL to icon which will be displayed as open conversation window button
appearance.icons.minimizeButtonIconstringURL to icon which will be displayed as minimize conversation window button
appearance.icons.closeButtonIconstringURL to icon which will be displayed as close and reset conversation window button
appearance.icons.activeSendMessageButtonIconstringURL to icon which will be displayed as send message button (active)
appearance.icons.disabledSendMessageButtonIconstringURL to icon which will be displayed as send message button (disabled - not active)
appearance.icons.autoScrollToBottomIconstringURL to icon which will be displayed as scroll to bottom button
appearance.styles objectObject 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.urlstringUrl to custom stylesheet````styles: { url: '<https://cdn.sentione.com/chat-ui-launcher/themes/dark-blue.css>

', }```

````
appearance.styles.customCssstringCustom css rulesstyles: { customCss: '.chat-header__title {color: red;}', }
appearance.styles.themeColorstringMain color of webchatstyles: { themeColor: 'red', }
appearance.outerStylesobjectObject to setup mostly position of webchat on host page. These styles will be injected to host page
appearance.outerStyles.urlstringUrl to custom stylesheet
appearance.outerStyles.customCssstringCustom css rules
appearance.headerTitlestringUser will see it in header```headerTitle: "Sentione chat",

```
appearance.endOfConversationLabelstringUser will see this label as end of conversation message
appearance.startNewConversationButtonLabelstringUser will see this label in button to start new conversation
appearance.conversationWindowWidthstringField to set up width of the conversation window{conversationWindowWidth: '300px'}
appearance.conversationWindowHeightstringField to set up height of the converstion window{conversationWindowHeight: '300px'}
appearance.inputPlaceholderstringPlaceholder of the input
autoStartobject or numberField 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.delayTimenumberTime to delay automatically open chatautoStart: 2000
initialMessage objectObject to set up initial message. Thanks to it, bot can start from specific block`initialMessage: { text: "", extraData: { process: "process_name" }, },

````
initialMessage.extraDataobjectInitial extraData that will be sent to bot to start conversationextraData: { process: "process_name" }
silenceMessage object or numberOption to setup behaviour to handle missing message from a user`silenceMessage: { delayTime: 2000 }, or

silenceMessage: 2000

````
silenceMessage.delayTimenumberDelay value to send message while user is not respondingsilenceMessage: { delayTime: 2000 }
silenceMessage.extraDataobjectObject that will be send to bot while user is not responding`silenceMessage: { delayTime: 2000, text: "", extraData: {"process:" :"X"} }

````
silenceMessage.maxRepetitionnumberValue 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 214silenceMessage: { delayTime: 2000, extraData: {"process:" :"X"}, maxRepetition: 1 }
everyMessageobject
everyMessage.extraDataobjectField 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 objectObject to define which action buttons should be visible`actionButtons: { conversationWindow: { minimize: true }, }

````
actionButtons.conversationWindow.minimizebooleanShow or hide button to minimize conversation window`actionButtons: { conversationWindow: { minimize: true }, }

````
actionButtons.conversationWindow.resetAndMinimizebooleanShow or hide button to reset (clear) conversation and minimize conversation window`actionButtons: { conversationWindow: { resetAndMinimize: true }, }

````
languagestring ('en' | 'pl')Language to use by default, this is mostly important when errors occur (for example message can't be sent)'en'
scrollOptionsobject
scrollOptions.scrollTostring ('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.
sessionobject
session.hostSessionCookiebooleanTo enable conversation session cookie managed by frontend (better support by browsers like Safari)
onOpenChatfunctionCallback function`onOpenChat: () => { console.log('Chat is open'); }

````
onCloseChatfunctionCallback function`onCloseChat: () => { console.log('Chat is closed'); }

````
onInitializedChatfunctionCallback function`onInitializedChat: () => { console.log('Chat is initialized'); }

````
onOpeningButtonClickfunctionCallback function`onOpeningButtonClick: () => { console.log('User clicked to open chat'); }

````
onConversationEndfunctionCallback function`onConversationEnd: () => { console.log('End of conversation'); }

````
onMinimizeConversationWindowfunctionCallback function`onMinimizeConversationWindow: () => { console.log('User minimized conversation window'); }

````
onCloseConversationWindowfunctionCallback function`onCloseConversationWindow: () => { console.log('User closed conversation window'); }

````
onMessageSentfunction: (message: string) => void;
onMessageReceivedfunction: (response) => void;
onDestroyedChatvoidCallback 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)ArgumentsReturn typeDescription
isChatOpen()booleanMethod to check if conversation window is opened or closed
isChatInitialized()booleanMethod to check if webchat is available and initialized on page or not
initWebChat(configurationObject)configurationObject - objectvoidMethod to initialize webchat component on page
open()voidMethod to open (show) chat conversation window.
close()voidMethod to close conversation window and reset current conversation (it will also turn off silence Message functionality)
minimize()voidMethod 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()voidMethod 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 namePayloadpayload details
SET_CONFIGconfiguration ObjectThis is required event to set webchat ready to work. Read Configuration object chapter to get more info
START_CONVERSTAIONnullRequired event to start conversation by webchat. This event should be send to send first message bot.
CLOSE_CONVERSATIONnullEvent to close and reset conversation session and history.

Events send by webchat to host page

Event type namePayloadPayload details
WEBCHAT_READYnullEvent is sent by webchat to host page after webchat initialization.
CLIENT_MESSAGE_SENTmessageEvent is sent by webchat to host page after send message from user to bot
MESSAGE_RECEIVEDmessageEvent is sent by webchat to host page after webchat receive message from bot
CONVERSATION_ENDnullEvent is sent by webchat to host page after finish conversation.
CLOSE_CONVERSATION_WINDOWnullEvent is sent by webchat to host page after user click X icon from webchat's header
MINIMIZE_CONVERSATION_WINDOWnullEvent 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:

Updated 6 days ago