dialogshift-webchat-sdk

v2.9.4

Published

2 months ago

A client library for Dialogshift web chat

Downloads

279

0High
0Medium
0Low

dialogshift

Dialogshift Dialogshift javascript Dialogshift chat Dialogshift sdk

Dialogshift Webchat SDK

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

SDK Demo

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]

Resources