WebSocket events

Websocket (Socket.io) events emitted by the websocket server (hosted separately from the REST API).

Connecting / channels. Every channel is a Socket.io namespace named /{resourceType}/{resourceId}[/{visibility}], where resourceType is one of workspace, project, user, chat, asset, submission, task or public, resourceId is a UUID (or legacy 24-char hex id) and the optional visibility is creator, reviewer or public. Public release channels are /public/{token} (10-character public token, no visibility suffix). Any other namespace is refused. Authenticate by passing query: { token } on the handshake: a user JWT, a personal access token or a bot API key (bot keys must connect through a configured bot gateway hostname). /public/{token} namespaces need no handshake token (the token in the namespace is validated instead); authenticated users may also join them. Failures surface as connect_error with message forbidden (invalid credentials or no permission) or badRequest (malformed channel / permission lookup error).

Permissions. A user may only join their own /user/{userId}. /project/{id}/creator, /reviewer and /public require canGetProjectCreatorNotifications, canGetProjectReviewerNotifications and canGetProjectPublicNotifications respectively; every other channel requires canGet{ResourceType}Notifications (direct or inherited).

Server -> client events: notification (every notification event documented below, emitted on each channel in the notification's channels list; the payload type selects the schema), tokenEvent, typing:start / typing:stop and the collab:* events (only on /chat/{chatId} namespaces). Client -> server events: ws:probe, typing:start / typing:stop, collab:*. Sockets whose JWT expired or was blacklisted, or whose bot key was revoked, receive tokenEvent and are disconnected shortly after.

Each event type below is documented using 'get' to represent the emitted event payload under the '200' response schema. Keys marked with (*) will be deprecated in a future release and should not be used for new development and should be replaced with values and objects in the changes key in existing implementations.

Servers

Channels

Channels are Socket.IO namespaces. Connect a Socket.IO client to the namespace address; do not open a raw WebSocket.

Resource namespace

Address: /\{resourceType\}/\{resourceId\}/\{visibility\}

Notifications for one workspace, project, user, chat, asset, submission or task.

Socket.IO namespace named after the resource. The /{visibility} segment is optional: connect to /{resourceType}/{resourceId} for the default channel. Requires a handshake token. A user may only join their own /user/{userId}; /project/{id}/creator, /reviewer and /public require canGetProjectCreatorNotifications, canGetProjectReviewerNotifications and canGetProjectPublicNotifications; every other channel requires canGet{ResourceType}Notifications (direct or inherited).

Public release namespace

Address: /public/\{token\}

Notifications for one public release, authenticated by the token in the namespace name.

No handshake token is needed (authenticated users may still send one). No visibility suffix. Typing indicators for chats that belong to the release are relayed here as well.

Collab session namespace

Address: /chat/\{resourceId\}

Real-time collaboration relay (cursors, drawing, presenter control) between the sockets of one chat.

The relay runs on namespaces starting with /chat/; the same connection also receives the notification events of the resource namespace. Relayed payloads are enriched server-side with the authenticated user identity, so client supplied identity keys are overwritten.

Events

Notification types

126 notification types are delivered inside the notification envelope. See Notification types.