Dialogshift Webchat SDK

A client library for embed Dialogshift webchat to webpages. Written in TypeScript and published in UMD and ES2015.

About
How it works
Getting started
API methods
Events
Getting help
Resources

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 support@dialogshift.com
    email: 'foo@bar.baz',
    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 support@dialogshift.com

Resources

SDK Demo

https://www.dialogshift.com

SDK NPM page

dialogshift-webchat-sdk