dialogshift-webchat-sdk
v2.9.5
Published
A client library for Dialogshift web chat
Downloads
75
Maintainers
Readme
Dialogshift Webchat SDK
A client library for embed Dialogshift webchat to webpages. Written in TypeScript and published in UMD
and ES2015
.
Table of Contents
About
Dialogshift is a Conversational AI platform that helps businesses to improve communication with their customers, enhance the customer experience and ultimately grow revenue through customer retention and automation.
Messaging is an intuitive communication tool and has the ability to bring brands much closer to their customers, increasing the engagement through more frequent 1:1 touchpoints.
This SDK allows to embedding Dialogshift webchat to webpages, customize and control chat widgets, change conversational flow as you need, communicate with Conversational AI platform. Webchat widgets are fully responsive for desktop, tablet or mobile pages. SDK has native JavaScript and TypeScript versions.
How it works
SDK and chat workflow phases.
Loading scripts
Starts when js and css scripts are injected into a webpage. After scripts are loaded SDK is waiting for initialization.
SDK initialization
Starts when user calls Dialogshift.instance(...options)
for the first time.
- SDK loads Webconfig with settings, custom css, custom options.
- Renders toggle button and other widgets on webpage.
- Fires event
init
. User can read chat config or work with widgets.
Chat loading
Starts when chat window is manually or programmatically opened for the first time.
- SDK loads chat app inside iframe.
- Chat establishes a connection with a message layer.
- Chat loads message history and trigger an initial message if needs.
- Fires event
ready
.
Chat destroying
Starts when Dialogshift.destroy()
is called.
- SDK unbinds all events, removes chat iframe and widgtes from a webpage.
- Fires event
destroy
.
Getting started
You can install SDK using npm
or use CDN link directly. To obtain app id
signup and copy id
from Member area.
Replace %id%
in snippets below with your app id
and initialize Dialogshift chat instance. Your app will interact with the chat client through the instance Dialogshift.instance()
, which will available in your scope.
Install from npm
Install package
npm i dialogshift-webchat-sdk --save
Import and initialize chat instance
import * as Dialogshift from 'dialogshift-webchat-sdk'
import 'dialogshift-webchat-sdk/bundles/dialogshift-webchat-sdk.min.css'
const chat = Dialogshift.instance({
id: '%id%',
})
Include from CDN
Add the following code towards the end of <head>
section of your page.
<script
type="text/javascript"
src="https://cdn.dialogshift.com/sdk/latest/dialogshift-webchat-sdk.umd.js"></script>
<link
rel="stylesheet"
type="text/css"
href="https://cdn.dialogshift.com/sdk/latest/dialogshift-webchat-sdk.min.css"/>
Add the following code towards the end of <body>
section of your page.
<script type="text/javascript">
var chat = Dialogshift.instance({
id: '%id%',
})
</script>
API methods
instance(chatConfig config): ChatInstance
Creates a new one chat instance or returns previously created instance. Returns singleton instance.
chatConfig
| Property | Type | Description |
| ----------------- | ----------------- |--------------------------------------------------------------------------------------------------------------------|
| id | string | Client id obtained from the application dashboard. |
| locale? | string | Chat locale. Defaults to en
. |
| position? | 'left' | 'right' | Chat position on webpage. Defaults to right
. |
| isChatboxVisible? | boolean | Show chat window expanded if true
. Defaults to false
. |
| isButtonVisible? | boolean | Show toggle button if true
. Defaults to true
. |
| renderButton? | boolean | Render toggle button if true
. If button is not rendered show or hide it later is impossible. Defaults to true
. | |
| initialElement? | string | Trigers initial message. |
| unreadCounter? | number | Amount of unread messages. |
| theme? | 'round' | 'tile' | UI theme. Defaults to round
. |
| context? | object | Context variables for visitor. |
First time initialization.
const client = Dialogshift.instance({
id: '%id%',
locale: 'de',
position: 'left',
initialElement: 'welcome-message',
unreadCounter: 2,
context: {
channel: 'pwa-ibe', // pwa-ibe (Booking Engine), pwa-guestapp (Generic guest-app), for additional codes contact [email protected]
email: '[email protected]',
name: 'John Doe'
}
})
// Returns the same instance
console.log(client === Dialogshift.instance()) // true
destroy()
Destroys current instance.
Dialogshift.instance().destroy()
isDestroyed(): boolean
Returns true
if chat is destroyed.
Dialogshift.instance().isDestroyed()
on(string eventName, function handler)
Listen on a new event by type and handler. The handler will not be listened if it is a duplicate.
Dialogshift.instance().on('ready', () => {
console.log('Chat is ready to send messages')
})
once(string eventName, function handler)
Listen on a once event by type and handler. The handler will not be listened if it is a duplicate.
Dialogshift.instance().once('chatbox.show', () => {
console.log('Chat is opened for the first time')
})
off(string eventName?, function handler?)
Listen off an event by type and handler. Or listen off events by type, when if only type argument is passed. Or listen off all events, when if no arguments are passed.
Dialogshift.instance().off('chatbox.show')
//OR
Dialogshift.instance().off()
offAll()
Listen off all events.
Dialogshift.instance().offAll()
showChatbox()
Show chatbox.
Dialogshift.instance().showChatbox()
hideChatbox()
Hide chatbox window.
Dialogshift.instance().hideChatbox()
showButton()
Show toggle button.
Dialogshift.instance().showButton()
hideButton()
Hide toggle button.
Dialogshift.instance().hideButton()
setButtonText(string text)
Change toggle button text. text
could be an empty string.
Dialogshift.instance().setButtonText('Help')
// OR to remove button text
Dialogshift.instance().setButtonText('')
showTeaser()
Show teaser.
Dialogshift.instance().showTeaser()
hideTeaser()
Hide teaser.
Dialogshift.instance().hideTeaser()
setTeaserText(string text)
Change teaser text.
Dialogshift.instance().setTeaserText('👋🏻 Hi, can I help you?')
setPosition('left' | 'right' position)
Change chat container position regarding left or right of the window.
Dialogshift.instance().setPosition('left')
isChatboxVisible(): boolean
Returns true
if chatbox window is opened.
Dialogshift.instance().isChatboxVisible()
setContext(string key, string | object value): Promise
Send additional context information to the chat instance.
Dialogshift.instance()
.setContext('currentUser', 'John Doe')
.then(() => {
console.log('Context is written')
})
// OR rewrite previous variable
Dialogshift.instance()
.setContext('currentUser', 'Jane Doe')
.then(() => {
console.log('Context is overwritten')
})
// OR write object
Dialogshift.instance()
.setContext('currentUser', {
firstName: 'John',
lastName: 'Doe',
})
.then(() => {
console.log('Context is written')
})
getContext(string key): Promise
Returns context variable.
Dialogshift.instance().setContext('visitor', {
firstName: 'John',
lastName: 'Doe',
})
// ...
Dialogshift.instance()
.getContext('visitor')
.then(visitor => {
console.log(visitor.firstName) // John
console.log(visitor.lastName) // Doe
})
// OR returns null if context is not setted
Dialogshift.instance()
.getContext('user')
.then(user => {
console.log(user === null) // true
})
setUnreadCounter(number amout)
Set value to unread counter widget. If amount = 0
widget will be hidden.
Dialogshift.instance().setUnreadCounter(2)
// OR to hide counter
Dialogshift.instance().setUnreadCounter(0)
increaseUnreadCounter()
Increase unread counter widget value.
Dialogshift.instance().increaseUnreadCounter()
getConfig(): Config
Returns chat config.
const config = Dialogshift.instance().getConfig()
triggerElement(options: TriggerElementOptions)
Triggers answer from chatbot content.
TriggerElementOptions
| Name | Type | Description |
| ----------------------- | ------- | -------------------------------------------------------------- |
| successor | string | Conversational element to trigger. |
| showChatbox? | boolean | If true chat window will be opened. Default to true
|
| suppressInitialElement? | boolean | If true initial element will be suppressed. Default to false
|
Dialogshift.instance().triggerElement({
successor: 'welcome-message',
suppressInitialElement: true,
})
setInitialElement(element: InitialElement)
Set a initial element.
Dialogshift.instance().setInitialElement({
successor: 'welcome-1',
suppress: false,
})
InitialElement
| Name | Type | Description |
| --------- | ------- | -------------------------------------------------------------- |
| successor | string | Initial message to trigger |
| suppress | boolean | If true initial element will be suppressed. Default to false
|
getInitialElement(): InitialElement
Returns current initial element.
Dialogshift.instance().getInitialElement()
setTheme(theme: AppTheme): InitialElement
Set an UI theme.
Dialogshift.instance().setTheme('tile')
AppTheme
| Name | Type | Description | | --------- | ------- | -------------------------------------------------------------- | | round | string | UI theme | | tile | string | UI theme |
isReady(): boolean
Returns true
if chat is fully loaded and ready to communicate.
Dialogshift.instance().isReady()
setActionButtons(buttons: ActionButton[])
Remove current action buttons and render new.
Dialogshift.instance().setActionButtons([{
type: 'quickreply',
successor: 'welcome-back',
de: {
title: 'Welcome back',
},
en: {
title: 'Welcome back',
},
}])
ActionButton
| Name | Type | Description |
| --------- | ------- | -------------------------------------------------------------- |
| type | string | Type of action. Possible values quickreply
. |
| successor | string | Message to trigger |
| de | object | Button title for DE locale |
| en | object | Button title for EN locale |
showActionButtons()
Show action buttons.
Dialogshift.instance().showActionButtons()
hideActionButtons()
Hide action buttons.
Dialogshift.instance().hideActionButtons()
setLocale(locale: string)
Changes current locale, updates widget content.
Dialogshift.instance().setLocale('de')
Events
You can subscribe to events to receive callbacks when events happen. Bind and unbind methods described in section API Methods.
| Name | Payload | Description |
| ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| init | | Fires once when the chat DOM is ready, widgets are rendered and chat config is loaded. You can call API methods but can't send messages because chat is not connected. |
| ready | | Fires once when the chat DOM is ready, configuration is loaded and chat connected to conversational channel. You can send messages. Mind that chat connects to conversational channel only after first open. |
| chatbox.show.before | | Fires before the chat window is shown. |
| destroy | | Fires once when the chat is destroyed. |
| chatbox.show | | Fires whenever the chat window is shown. |
| chatbox.hide.before | | Fires before the chat window is hidden. |
| chatbox.hide | | Fires whenever the chat window is hidden. |
| button.show.before | | Fires before the toggle button is shown. |
| button.show | | Fires whenever the toggle button is shown. |
| button.hide.before | | Fires before the toggle button is hidden. |
| button.hide | | Fires whenever the toggle button is hidden. |
| message.sent | RequestModel
| Fires whenever a visitor sent message. |
| message.receive | MessageModel
| Fires whenever a visitor received message. |
| command.receive | CommandModel
| Fires whenever a visitor received command. |
Event init
example.
const client = Dialogshift.instance()
client.on('init', () => {
console.log('Widgets are rendered and webconfig is loaded')
client.showChatbox()
})
Event ready
example.
const client = Dialogshift.instance()
client.on('ready', () => {
console.log('SDK connected to a channel')
client.triggerElement({
successor: 'welcome-message',
})
})
Event chatbox.show
example.
const client = Dialogshift.instance()
client.on('chatbox.show.before', () => {
console.log('Chat window is going to be shown')
})
client.on('chatbox.show', () => {
console.log('Chat window shown')
})
Event message.sent
example.
const client = Dialogshift.instance()
client.on('message.sent', event => {
const requestModel = event.data
if (requestModel.requestType === 'text') {
console.log('The visitor sent message: ' + requestModel.text)
}
})
RequestModel
| Name | Description |
| ----------- | --------------------------------------------------------------------------------------------- |
| requestType | Type of the sent message. Possible values command
, text
, button
, feedback
, trigger
. |
RequestModel contains different fields correspond to requestType.
Event message.receive
example.
const client = Dialogshift.instance()
client.on('message.receive', event => {
const messageModel = event.data
console.log(messageModel)
console.log('The visitor got message')
})
MessageModel
| Name | Type | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| datetime | datetime | Time in a datetime
format. |
| fromHistory | boolean | Source of the message. |
| isLiveMode | boolean | true
if user got the message from a operator. |
| elementType | string | Type of element inside the message. Possible values feedback
, text
, button
, carousel
, list
,book
, dateRange
,image
. |
MessageModel contains different fields correspond to elementType type.
Event command.receive
example.
const client = Dialogshift.instance()
client.on('command.receive', event => {
const commandModel = event.data
if (commandModel.commandType === 'setLanguage') {
console.log(
'The visitor got command to change locale to ' + commandModel.lg
)
}
})
CommandModel
| Name | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| commandType | string | Type of command. Possible values url
, setLanguage
, typingIndicatorOn
,typingIndicatorOff
, livechat
,log
, actionBroker
, setTeaserText
. |
CommandModel contains different fields correspond to commandType type.
Getting help
Please use our Github issue tracker for questions, feature requests, suggestions, bug reports or any kind of feedback. Or email us to [email protected]