Embed the chat in a guest app

To embed the webchat in a guest-facing web app (e.g. a PWA or a web view embedded in an app), use the Webchat SDK. It provides the full widget behavior and programmatic control through methods and events.

Prerequisites

The Client ID of your app. You find it in the DialogShift dashboard. For development and testing you can use the demo Client ID pro12bd.
The channel code of the source. For a guest app it must be set to exactly pwa-guestapp. The channel code lets us attribute conversations to the correct source.

The channel code cannot be chosen freely. For a guest app, set it to exactly pwa-guestapp. Additional channel codes only in coordination with DialogShift Support.

Integration via SDK

The SDK renders the toggle button and the chat window, loads the chat inside an iframe, and exposes methods to control it. It is available as a UMD and ES2015 bundle.

Install the SDK

npm i dialogshift-webchat-sdk --save

<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"/>

Initialize the chat

Set your Client ID as id and the channel code through context.channel. The example uses the demo Client ID pro12bd.

import * as Dialogshift from 'dialogshift-webchat-sdk'
import 'dialogshift-webchat-sdk/bundles/dialogshift-webchat-sdk.min.css'

const chat = Dialogshift.instance({
  id: 'pro12bd',
  locale: 'en',
  context: {
    channel: 'pwa-guestapp',
    email: 'guest@example.com',
    name: 'John Doe',
  },
})

Dialogshift.instance() returns a singleton: calling it again without arguments returns the same instance.

Key options

Option	Type	Description
id	string	Client ID from the dashboard.
locale	string	Chat locale. Defaults to `en`.
position	’left’ \| ‘right’	Position on the page. Defaults to `right`.
isChatboxVisible	boolean	Opens the chat window immediately if `true`. Defaults to `false`.
renderButton	boolean	Renders the toggle button. If it is not rendered, it cannot be shown or hidden later. Defaults to `true`.
initialElement	string	Element triggered automatically when the chat is opened for the first time, e.g. a welcome message.
context	object	Context variables for the visitor (including `channel`).

Full-screen integration: chat only

The most common case in a guest app: the screen should show only the chat, without a floating button. To do this, skip rendering the button and open the chat window immediately.

const chat = Dialogshift.instance({
  id: 'pro12bd',
  locale: 'en',
  renderButton: false,
  isChatboxVisible: true,
  initialElement: 'welcome-message',
  context: {
    channel: 'pwa-guestapp',
  },
})

With initialElement the specified element is triggered automatically on open - the guest immediately sees a welcome message.

Lifecycle: `init` and `ready`

The SDK fires two central events:

init fires once the widgets are rendered and the configuration is loaded. From now on you can call API methods, but you cannot trigger messages yet.
ready fires once the chat is connected to the messaging channel. The connection is only established when the chat window is opened for the first time - if it stays closed, ready never fires.

Controlling at runtime

const chat = Dialogshift.instance()

// Wait for the connection before triggering messages
chat.on('ready', () => {
  chat.triggerElement({ successor: 'welcome-message' })
})

// Open the chat window - establishes the connection on first open
chat.showChatbox()

// Set context later
chat.setContext('currentUser', { firstName: 'John', lastName: 'Doe' })

// Tear down the instance (e.g. when leaving the view)
chat.destroy()

More methods and events

The SDK also offers methods for teasers, button text, unread counters, and themes, as well as events for sent and received messages. You find the full API reference in the Webchat SDK GitHub README; the SDK demo shows the widget behavior live.

Overview

Onboarding

Basic Settings

Agents

DialogShift Services

Prerequisites

Integration via SDK

Key options

Full-screen integration: chat only

Lifecycle: `init` and `ready`

Controlling at runtime

More methods and events

​Prerequisites

​Integration via SDK

​Key options

​Full-screen integration: chat only

​Lifecycle: init and ready

​Controlling at runtime

​More methods and events

Prerequisites

Integration via SDK

Key options

Full-screen integration: chat only

Lifecycle: `init` and `ready`

Controlling at runtime

More methods and events