Web Chat Configuration

Web Chat configuration controls how the widget looks, behaves, and presents itself to visitors. YS Desk provides two configuration surfaces: dashboard settings for persistent Web Chat configuration and SDK runtime options for client-side behavior.

Configuration Overview

Web Chat configuration is managed through the YS Desk dashboard and the Web Chat SDK.

Dashboard Configuration

In the YS Desk dashboard, Web Chat settings are available under:

Settings → Chatbox Settings

The available sections are:

  • Chatbox Appearance — Configure Web Chat appearance and workspace branding.
  • Chat Launcher — Configure launcher position, style, animation, text, and offsets.
  • Welcome Message — Configure the welcome message and pre-chat greeting.
  • Offline Message — Configure the message shown when the support team is unavailable.
  • Chat Settings — Configure available Web Chat feature toggles.

The dashboard provides the persistent configuration used by Web Chat.

SDK Runtime Configuration

The Web Chat SDK accepts client-side configuration through the run command:

window.YSDeskSDK(‘run’, {

  token: ‘YOUR_CHANNEL_TOKEN’

});

Runtime configuration can provide client-specific values such as visitor information, launcher visibility, initialization behavior, and lifecycle callbacks.

See [Web Chat → SDK Reference] for the complete SDK configuration reference.

Dashboard Settings Overview

Navigating to Web Chat Settings

In the YS Desk dashboard, open:

Settings → Chatbox Settings

From there, select the configuration area you want to manage:

Chatbox Appearance

Configure Web Chat appearance and workspace branding.

Chat Launcher

Configure launcher position, style, animation, text, and offsets.

Welcome Message

Configure the welcome message and pre-chat greeting.

Offline Message

Configure the offline message.

Chat Settings

Configure Web Chat feature toggles.

Figure WC-08 — Navigating to Chatbox Settings in the YS Desk dashboard sidebar.

Appearance & Branding

The Chatbox Appearance section controls the visual branding of Web Chat.

Available settings include the primary color, gradient configuration, launcher icon color, and workspace identity.

Figure WC-09 — The YS Desk Web Chat configuration interface showing Identity & Branding, Chat Launcher, and Chat Settings with a desktop live preview.

Chat Launcher

The Chat Launcher section controls how the floating Web Chat launcher is presented.

Available settings include launcher style, position, text, animation, offsets, and supported visual effects.

Figure WC-10 — Chat Launcher settings for configuring the launcher style, position, aesthetic, label, animation, visual effects, and spacing.

For the complete launcher configuration, see [Web Chat → Launcher].

Welcome Message

The Welcome Message section controls the message displayed during the Web Chat welcome experience.

It also contains the Pre-chat Greeting used in the pre-chat experience.

The Welcome Message supports up to 100 characters, while the Pre-chat Greeting supports up to 50 characters.

Figure WC-11 — Welcome Message settings for configuring the message shown when a visitor starts a new conversation, including the pre-chat greeting.

For detailed offline-message behavior, see [Web Chat → Configuration].

Offline Message

The Offline Message section controls the message displayed when the support team is unavailable.

The message supports up to 250 characters.

Figure WC-12 — Offline Message settings for configuring the automatic message shown when all agents are unavailable.

For detailed offline-message behavior, see [Web Chat → Configuration].

Chat Settings

The Chat Settings section contains Web Chat feature toggles.

The available settings include:

Rich Media Uploads
 Controls whether visitors can upload supported media through Web Chat.

Satisfaction Surveys
 Controls whether customer satisfaction surveys are enabled.

Figure WC-13 — Chat Settings showing Rich Media Uploads and Satisfaction Surveys feature toggles.

For file upload and customer satisfaction configuration, see [Web Chat → Messaging & Media].

SDK Runtime Configuration

Runtime configuration is supplied when initializing the Web Chat SDK.

window.YSDeskSDK(‘run’, {

  token: ‘YOUR_CHANNEL_TOKEN’

});

The SDK also supports client-specific runtime options.

Client-Specific Options

Supported runtime options include:

OptionPurpose
userEmailProvides visitor email information.
userNameProvides visitor name information.
lazyControls lazy initialization behavior.
launcher.showControls whether the launcher is displayed.
launcher.tooltipSets launcher tooltip text.
theme.darkModeControls the runtime dark-mode preference.
onOpenRuns when Web Chat opens.
onCloseRuns when Web Chat closes.
onReadyRuns when the SDK is ready.
embeddedAppEnables supported embedded application behavior.
supportSessionProvides supported support-session context.

The Channel Token is required for SDK initialization.

Runtime Configuration Example

A client application can provide runtime options together with the Channel Token:

window.YSDeskSDK(‘run’, {

  token: ‘YOUR_CHANNEL_TOKEN’,

  userEmail: ‘alex.smith@example.com’,

  userName: ‘Alex Smith’,

  lazy: true,

  launcher: {

    show: true,

    tooltip: ‘Chat with our support team’

  },

  theme: {

    darkMode: true

  },

  onReady: () => {

    console.log(‘YS Desk Web Chat SDK is fully loaded.’);

  },

  onOpen: () => {

    console.log(‘Chat widget opened.’);

  },

  onClose: () => {

    console.log(‘Chat widget minimized.’);

  }

});

For the complete runtime option reference and supported SDK methods, see [Web Chat → SDK Reference].

Configuration Precedence

Dashboard settings and SDK runtime options are not resolved using one universal override rule.

For visual and launcher properties that are configured in the dashboard, the dashboard configuration is authoritative.

The general resolution model is:

SDK Built-in Defaults
↓
SDK Runtime Configuration
↓
YS Desk Dashboard Configuration
↓
Effective Web Chat Configuration

For example, the dashboard may define:

Primary Color: #10B981

while the SDK provides:

theme: {

  primaryColor: ‘#F59E0B’

}

The dashboard value is applied to the Web Chat.

SDK theme values for these properties therefore act as runtime fallbacks rather than final overrides.

Runtime-only properties that do not have corresponding dashboard settings remain controlled by the SDK initialization.

Configuration Rule

Use the following rule when combining dashboard and SDK configuration:

  • Dashboard settings take precedence for supported visual and launcher properties configured for the Web Chat channel.
  • SDK runtime options control client-specific behavior when no corresponding dashboard configuration exists.

Do not assume that every SDK option overrides every dashboard setting.

Saving and Resetting Configuration

Saving Changes

Appearance and launcher settings are edited in the dashboard and saved using Save Changes.

The configuration interface tracks unsaved changes. Leaving a page while changes are pending can display a confirmation asking whether the unsaved changes should be discarded.

Automatically Saved Features

The Rich Media Uploads and Satisfaction Surveys feature toggles are saved immediately when changed.

The interface displays a loading state while the update is being processed.

Welcome and Offline Messages

Welcome and Offline Message settings use an edit-and-save workflow.

  1. Click Edit Message.
  2. Modify the message.
  3. Click Save Changes.

When there are unsaved changes, leaving the page can display the Discard Unsaved Changes? confirmation.

These sections use Revert to Saved to restore the currently saved message value.

Revert to Saved is different from Reset Defaults. It restores the currently saved value rather than the system default.

Resetting to Defaults

The Reset Defaults control is section-scoped.

Clicking Reset Defaults immediately restores the defaults for the current section and persists those values. A second confirmation dialog is not displayed.

Figure WC-14 — Discard Unsaved Changes confirmation dialog shown while editing Web Chat appearance settings.

For example:

  • Appearance restores the default branding configuration.
  • Launcher restores the default launcher configuration.
  • Chat Settings restores the supported feature-toggle defaults.

Resetting one section does not reset unrelated Web Chat configuration.

Plan & Feature Availability

Some Web Chat configuration features require a paid subscription plan.

Free Plan

On the Free plan:

  • The Welcome Message remains on its default value and cannot be freely edited.
  • The Offline Message configuration is gated.
  • Satisfaction Surveys are gated.

The Pre-chat Greeting remains available for configuration.

Starter Plan and Above

The Chat Launcher, Welcome Message, Offline Message, and Satisfaction Surveys require the Starter plan or above.

The dashboard displays the appropriate upgrade or locked state when a feature is unavailable.

Live Preview

The Web Chat configuration interface provides a desktop live preview for supported appearance and launcher settings.

The preview:

  • Appears on desktop layouts.
  • Reflects draft changes while editing Identity & Branding and Chat Launcher.
  • Uses a desktop-style browser preview.
  • Does not provide a mobile viewport preview.
  • Is not displayed on the Welcome Message or Offline Message configuration pages.

Use the preview to review supported appearance and launcher changes before saving.

Figure WC-15 — Desktop live preview reflecting draft Identity & Branding and Chat Launcher configuration changes.

Applying Configuration Changes

The general configuration lifecycle is:

Administrator Changes Web Chat Settings
↓
Settings Saved or Auto-Saved
↓
Configuration Updated
↓
Active Web Chat Receives Supported Updates
↓
Effective Widget Behavior Changes

Supported configuration changes can be propagated to active Web Chat sessions in real time.

The exact behavior depends on where the affected UI is rendered. Settings used inside the Web Chat interface can update while a session is active. The floating launcher is rendered separately on the host website, so launcher configuration changes may require the host page to be refreshed or navigated before the updated launcher configuration is applied.

Configuration Scope

Web Chat configuration is not uniformly scoped to a single channel.

Channel Configuration

Appearance, launcher, and channel-level feature settings are associated with the Web Chat channel.

Workspace Configuration

The following message settings are managed at the workspace level:

  • Welcome Message
  • Pre-chat Greeting
  • Offline Message

These workspace-level message settings can apply across the Web Chat channels associated with the workspace.

Need Help?

Email: support@ysdesk.com

Documentation: https://docs.ysplugins.com/ys-desk

Next

Web Chat Launcher
Web Chat Identity & Sessions
Web Chat Messaging & Media