System & Notification Events
System events synchronize Workspace-wide changes that are not part of the core message or conversation lifecycle. These include mentions, channel configuration updates, Saved Reply changes, permissions, Workspace lifecycle notifications, billing, analytics, and session termination.
Event Matrix
| Event | Direction | Purpose |
| mention:new | Server → Client | Announces a newly created mention |
| mention:deleted | Server → Client | Announces a deleted mention |
| mention:read | Server → Client | Synchronizes mention read state |
| channel:settings:update | Server → Client | Synchronizes channel configuration |
| canned_response:update | Server → Client | Synchronizes Saved Reply changes |
| permission:update | Server → Client | Synchronizes member access changes |
| user:blocked | Server → Client | Announces Workspace blocking |
| workspace:pending-deletion | Server → Client | Announces pending Workspace deletion |
| workspace:restored | Server → Client | Announces Workspace restoration |
| billing:updated | Server → Client | Announces billing state changes |
| analytics:live:kpis:updated | Server → Client | Updates Live Monitor KPIs |
| session:force-closed | Server → Client | Terminates an active Agent session |
Mention Events
mention:new is emitted when a Team Member is mentioned in a message.
{
“mention”: {
“id”: “<MENTION_ID>”,
“conversationId”: “<CONVERSATION_ID>”,
“messageId”: “<MESSAGE_ID>”,
“mentionedUserId”: “<USER_ID>”,
“mentionedBy”: “<USER_ID>”,
“createdAt”: “2026-09-10T10:15:00.000Z”,
“isRead”: false
}
}
mention:read synchronizes the read state of the mention, while mention:deleted is emitted when the corresponding mention is removed.
Channel Settings Updates
channel:settings:update allows connected clients to react to channel configuration changes.
Example fields include:
{
“id”: “<SETTINGS_ID>”,
“channelId”: “<CHANNEL_ID>”,
“name”: “Support”,
“domain”: “example.com”,
“primaryColor”: “#582AF5”,
“position”: “bottom-right”,
“launcherIcon”: “default”,
“allowUploads”: true,
“csatEnabled”: true,
“welcomeMessage”: “How can we help?”
}
Saved Reply Synchronization
The canned_response:update event synchronizes Saved Reply creation, updates, and deletion across Agent clients.
{
“workspaceId”: “<WORKSPACE_ID>”,
“responseId”: “<RESPONSE_ID>”,
“userId”: “<USER_ID>”,
“action”: “update”,
“cannedResponse”: {}
}
The user-facing concept is Saved Reply even though the underlying event name retains canned_response.
Permission Updates
permission:update communicates Workspace access changes such as role updates, restrictions, blocking, member removal, and permission synchronization.
{
“eventId”: “<EVENT_ID>”,
“ts”: 1787309000000,
“userId”: “<USER_ID>”,
“workspaceId”: “<WORKSPACE_ID>”,
“permissionsVersion”: 4,
“reason”: “role.updated”,
“newRole”: “ADMIN”,
“restricted”: false,
“blocked”: false,
“removed”: false,
“permissions”: {
“message:send”: true,
“message:internal_note”: true,
“conversation:assign”: true,
“settings:edit”: true
}
}
Workspace Lifecycle
workspace:pending-deletion announces that a Workspace has entered the retention period before deletion.
{
“workspaceId”: “<WORKSPACE_ID>”,
“expiresAt”: “2026-09-17T10:00:00.000Z”,
“pendingDeletion”: true,
“message”: “Workspace is pending deletion.”,
“errorCode”: “WORKSPACE_PENDING_DELETION”
}
workspace:restored announces restoration from the pending-deletion state.
Billing and Analytics
billing:updated communicates Workspace billing state changes, including plan or invitation-related changes.
analytics:live:kpis:updated updates Live Monitor metrics such as active chats and waiting queue counts.
Session Force Closure
session:force-closed informs an Agent client that its session has been terminated because of inactivity or an administrative action.
{
“reason”: “idle_timeout”,
“message”: “Session has been closed.”
}
Internal Events
The following backend events are not public developer events and should not be implemented against:
login:new
login:logout
login:duration
ownership:transfer-initiated
ownership:transfer-completed
ownership:transfer-declined
BULK_MESSAGE_SEEN
user:updated
These events belong to internal telemetry, administrative security workflows, or deprecated compatibility behavior.
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk