Workspace & Channel Objects

Workspace and Channel objects define the primary scope of YS Desk data and the communication entry points connected to a Workspace.

Workspace Object

A Workspace is the primary container for YS Desk configuration and operational data. Channels, Team Members, Visitors, Conversations, and subscription information are associated with a Workspace.

Fields

Field	Type	Required	Nullable	Default	Description
id	string	Yes	No	Generated	Unique Workspace identifier.
uuid	string	No	Yes	Generated	Public external identifier.
name	string	Yes	No	—	Workspace display name.
website	string	Yes	No	—	Primary business website or domain.
logo	string	No	Yes	null	Workspace branding image URL.
status	WorkspaceStatus	Yes	No	ACTIVE	Current Workspace lifecycle state.
timezone	string	Yes	No	Asia/Kolkata	Default IANA timezone used for scheduling and business-hour related behavior.
appearance	ChannelAppearance	No	Yes	null	Web Chat appearance configuration.
metadata	WorkspaceMetadata	No	Yes	null	Company, language, and regional configuration.
notificationFrequency	NotificationFrequency	Yes	No	TWENTY_FOUR_HOURS	General notification delivery frequency.
unreadMessageFrequency	NotificationFrequency	Yes	No	TWENTY_FOUR_HOURS	Unread-message reminder frequency.
notificationStartTime	string	Yes	No	09:00	Preferred daily notification time in HH:mm format.
enableDailyDigest	boolean	No	Yes	null	Enables or disables daily digest behavior.
enableGuestEmailNotifications	boolean	Yes	No	false	Controls guest email notifications for supported offline replies.
createdAt	ISO-8601 timestamp	Yes	No	Generated	Workspace creation timestamp.
updatedAt	ISO-8601 timestamp	Yes	No	Generated	Last Workspace update timestamp.

Internal deletion markers and internal support-routing tokens are excluded from the public Reference specification.

Workspace Metadata

WorkspaceMetadata groups extended Workspace configuration.

Company Details

CompanyDetails contains business identity information used by Workspace configuration and billing-related functionality.

Language & Region

LanguageRegion contains language and regional preferences used for localized Workspace behavior.

Timezone Settings

TimezoneSettings contains timezone-related configuration associated with Workspace scheduling.

These composite structures are represented under the Workspace metadata property.

Workspace Lifecycle

State	Description
ACTIVE	Workspace is operational.
SUSPENDED	Workspace access is suspended.
PENDING_DELETION	Workspace is in its recoverable deletion period.
PURGED	Workspace data has been permanently purged.

Channel Object

A Channel represents a communication entry point belonging to a Workspace.

Fields

Field	Type	Required	Nullable	Default	Description
id	string	Yes	No	Generated	Unique Channel identifier.
uuid	string	Yes	No	Generated	Public external Channel identifier.
channelToken	string	Yes	No	Generated	Token used to initialize supported Web Chat integrations. Use <CHANNEL_TOKEN> in documentation.
type	ChannelType	Yes	No	WEB	Channel integration type.
status	ChannelStatus	Yes	No	ACTIVE	Current Channel operational state.
workspaceId	string	Yes	No	—	Identifier of the owning Workspace.
createdAt	ISO-8601 timestamp	Yes	No	Generated	Channel creation timestamp.
updatedAt	ISO-8601 timestamp	Yes	No	Generated	Last Channel update timestamp.

Channel Types

Value	Description
WEB	Embedded YS Desk Web Chat integration.
WHATSAPP	WhatsApp Business integration.
MOBILE	Mobile application integration.
WORDPRESS	WordPress integration.
SHOPIFY	Shopify integration.

Channel Status

Value	Description
ACTIVE	Channel is active.
PAUSED	Channel is paused.
TRASH	Channel is soft-deleted or moved to trash.
PURGED	Channel has been permanently removed.

Channel Appearance

ChannelAppearance contains the configuration used to control the visual presentation and launcher behavior of the Web Chat widget.

Field	Type	Default	Description
primaryColor	string	#582AF5	Primary widget and launcher color.
primaryColorEnd	string	null	Secondary color used for gradient presentation.
position	string	bottom-right	Widget placement. Supported values: bottom-right, bottom-left, top-right, top-left.
sideOffset	number	20	Horizontal screen offset in pixels.
bottomOffset	number	20	Bottom screen offset in pixels.
launcherLabel	string	Chat with us	Text displayed by the launcher.
launcherStyle	string	standard	Launcher visual style.
launcherIcon	string	null	Custom launcher icon URL or configured icon value.
launcherIconColor	string	#ffffff	Launcher icon color.
launcherLabelPosition	string	left	Floating label position relative to the launcher icon.
launcherTextPosition	string	right	Text position inside the launcher control.
showLauncherLabel	boolean	true	Controls launcher label visibility.
launcherAnimation	string	none	Launcher attention animation.
launcherLabelTypewriter	boolean	false	Enables typewriter behavior for the launcher label.
launcherGlassBlur	number	12	Backdrop blur amount in pixels.
launcherGlow	boolean	false	Enables launcher glow effect.
launcherSpeechBubble	boolean	false	Displays launcher text in a speech-bubble style.
allowUploads	boolean	true	Allows Visitors to attach files.
csatEnabled	boolean	true	Enables CSAT behavior after Conversation resolution.
messages	ChannelMessages	null	Structured welcome, offline, and onboarding message configuration.

The four supported position values are implementation-verified as bottom-right, bottom-left, top-right, and top-left.

Launcher Styles

Supported launcher styles include:

standard, expanded, glass, square, tab, skeuomorphic, neumorphic

Launcher Animations

Supported values:

none, pulse, wiggle

Channel Messages

Web Chat messages are represented through the structured messages composite.

{

  “messages”: {

    “welcome”: {

      “enabled”: true,

      “text”: “Hello! How can we help?”

    },

    “offline”: {

      “enabled”: true,

      “text”: “We’re currently offline.”

    },

    “onboardingMessage”: {

      “enabled”: true,

      “text”: “Send us a message to get started.”

    }

  }

}

The structured messages property is the current representation.

The following flat properties are deprecated:

• welcomeMessage
• offlineMessage
• onboardingMessage
• enableWelcomeMessage
• enableOfflineMessage
• enableOnboardingMessage

Use messages.welcome, messages.offline, and messages.onboardingMessage instead.

Safe Channel Example

{

  “id”: “<CHANNEL_ID>”,

  “uuid”: “<CHANNEL_UUID>”,

  “channelToken”: “<CHANNEL_TOKEN>”,

  “type”: “WEB”,

  “status”: “ACTIVE”,

  “workspaceId”: “<WORKSPACE_ID>”

}

Need Help?

Email: support@ysdesk.com

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