Overview
Real-Time Architecture & Overview
YS Desk provides real-time communication for Workspace Agents and Web Chat Visitors through Socket.IO-based WebSocket connections. Real-time events keep conversations, messages, presence, assignments, unread counts, visitor activity, and selected workspace changes synchronized without requiring continuous polling.
The platform uses the standard Socket.IO connection path /socket.io/ and a dual-namespace architecture. The default / namespace handles messaging, conversation lifecycle, visitor activity, typing, read receipts, and channel updates. The /user-status namespace handles agent presence, session activity, heartbeats, and permission synchronization.
Transport & Engine Protocol
YS Desk uses Socket.IO v4 with WebSocket transport. The backend gateway explicitly configures WebSocket transport, while the SDK connection layer permits HTTP long-polling only during the initial connection process.
The standard Engine.IO path is:
Connections are established against the YS Desk API host using HTTPS/WSS. Socket.IO provides the connection lifecycle, event delivery, and reconnection behavior used by the platform.
Dual Namespace Architecture
YS Desk exposes two active Socket.IO namespaces:
| Namespace | Primary purpose |
| / | Messaging, conversations, visitor activity, typing, read receipts, channel settings, and general real-time synchronization |
| /user-status | Agent presence, heartbeats, session activity, initial status synchronization, permissions, and access-control updates |
Agent dashboard clients may use both namespaces. Web Chat Visitor clients use the default / namespace.
Client Types
YS Desk real-time communication has two primary client types.
Workspace Agent clients represent the authenticated dashboard experience. They use an Auth0 access token and workspace context.
Web Chat Visitor clients represent visitors interacting with an embedded Web Chat experience. They authenticate using a signed Visitor Session token together with the channel token and visitor/session context.
Rooms & Isolation
Real-time events are scoped through Socket.IO rooms to prevent unrelated workspaces, channels, conversations, visitors, and users from receiving events.
Common room scopes include:
workspace:<workspaceId>
channel:<channelId>
conversation:<conversationId>
conversation:<conversationId>:internal
visitor:<guestId>
visitor_instance:<clientInstanceId>
user:<userId>
session:<sessionId>
The internal conversation room is reserved for Agent-side internal notes and prevents those events from being exposed to Web Chat Visitors.
Real-Time and REST Synchronization
Socket.IO provides live updates, while REST APIs provide authoritative state retrieval and incremental reconciliation.
This distinction is especially important after a temporary network interruption. Rather than requiring the server to replay every event missed by a disconnected client, clients reconcile message state through the incremental messages synchronization API and then resume normal socket subscriptions.
Figure RT-01 — Real-Time architecture overview showing client types, Socket.IO namespaces, room isolation, and REST synchronization fallback.
Event Domains
Real-time events are organized into four public domains:
Message Events cover sending, message creation, updates, deletion, delivery, seen receipts, and typing.
Conversation & Assignment Events cover conversation subscriptions, creation, updates, assignment, deletion, status changes, and unread synchronization.
Presence & Visitor Events cover Agent availability, visitor activity, visitor navigation, widget visibility, and proactive chat.
System & Notification Events cover mentions, channel settings, Saved Reply synchronization, permission updates, billing changes, analytics updates, and workspace lifecycle events.
Internal session telemetry and administrative security events are intentionally excluded from the public developer contract.
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk