WebSocket API Documentation

This document outlines the WebSocket API for the Worknation Chat application, managed by AppGateway.

1. Connection Setup

Clients should connect to the WebSocket server endpoint.

Authentication

Authentication is handled via a userId and token passed in the handshake.query during the initial WebSocket connection.

client.handshake.query.userId: (Required) The numeric ID of the connecting user.
The server uses WncUserGuard to protect most WebSocket events. If authentication fails during connection or for an event, the client might be disconnected or receive a WsException.

Online Status

The server maintains a list of currently connected (online) users. This is used, for example, to deliver messages directly to a receiver's socket if they are online.

2. Data Transfer Objects (DTOs)

`CreateMessageDto`

Used as the payload for the create_message event.

Field	Type	Validation	Description
`chat_id`	number	NotEmpty	The ID of the chat session.
`receiver_id`	number	NotEmpty	The ID of the message recipient.
`message`	string	NotEmpty	The content of the message.

3. WebSocket Events

Events are categorized by their direction: Client-to-Server (messages the client sends) and Server-to-Client (messages the server sends).

3.1. Connection Lifecycle Events (Handled by Server)

connection (Implicit Client-to-Server)

Description: Triggered when a new client establishes a WebSocket connection. The server attempts to authenticate the user using userId from client.handshake.query. If successful, the user is added to an internal list of online users.

Payload (Client Handshake Query): { userId: number }

disconnect (Implicit Client-to-Server)

Description: Triggered when a client's WebSocket connection is closed. The server removes the user from the internal list of online users.

3.2. Client-to-Server Events (Subscribed Messages)

`create_chat`

Description: Initiates the creation of a new chat session between the sender (connected user) and a specified receiver.

Payload: { receiver_id: number }

receiver_id (number): The ID of the user to start a chat with.

Server Response: Emits chat_created to the sender on success.

Error: Throws WsException on failure.

`create_message`

Description: Sends a new message within a chat.

Payload: CreateMessageDto (see section 2 for structure)

Server Response:

Emits response_message to the sender with the created message.

Emits response_message to the receiver (if they are online) with the created message.

Error: Throws WsException on failure.

Note: If the receiver is offline, a "TODO" in the code suggests sending an "inMail" (this behavior might not be fully implemented via WebSockets).

`seen_message`

Description: Marks messages within a specific chat as "seen" by the connected user.

Payload: { chat_id: number }

chat_id (number): The ID of the chat where messages should be marked as seen.

Server Response: None explicitly on success.

Error: Throws WsException on failure.

`chat_messages`

Description: Requests all messages for a specific chat.

Payload: { chat_id: number }

chat_id (number): The ID of the chat to retrieve messages for.

Server Response: Emits get_all_chat_messages to the sender with an array of message objects.

Error: Throws WsException on failure.

`get_chats`

Description: Requests all chat sessions for the connected user.

Payload: None (uses the authenticated user's ID).

Server Response: Emits updated_chat_list to the sender with an array of chat objects.

Error: Throws WsException on failure.

3.3. Server-to-Client Events (Emitted Messages)

`chat_created`

Description: Confirms that a new chat session has been successfully created.

Payload: The newly created chat object.

Recipient: The client that initiated the create_chat request.

`response_message`

Description: Delivers a new message.

Payload: The created message object.

Recipients:

The client that sent the create_message request.

The intended receiver of the message, if they are currently online.

`get_all_chat_messages`

Description: Provides the list of messages for a requested chat.

Payload: An array of message objects.

Recipient: The client that initiated the chat_messages request.

`updated_chat_list`

Description: Provides the updated list of chat sessions for the user.

Payload: An array of chat objects.

Recipient: The client that initiated the get_chats request.

4. Error Handling

Failures in processing WebSocket events will typically result in a WsException being thrown by the server. The client should be prepared to handle these exceptions. The error object usually contains a message property with details about the error.

Chat Web Sockets

WebSocket API Documentation#

1. Connection Setup#

Authentication#

Online Status#

2. Data Transfer Objects (DTOs)#

CreateMessageDto#

3. WebSocket Events#

3.1. Connection Lifecycle Events (Handled by Server)#

3.2. Client-to-Server Events (Subscribed Messages)#

create_chat#

create_message#

seen_message#

chat_messages#

get_chats#

3.3. Server-to-Client Events (Emitted Messages)#

chat_created#

response_message#

get_all_chat_messages#

updated_chat_list#

4. Error Handling#

WebSocket API Documentation

1. Connection Setup

Authentication

Online Status

2. Data Transfer Objects (DTOs)

`CreateMessageDto`

3. WebSocket Events

3.1. Connection Lifecycle Events (Handled by Server)

3.2. Client-to-Server Events (Subscribed Messages)

`create_chat`

`create_message`

`seen_message`

`chat_messages`

`get_chats`

3.3. Server-to-Client Events (Emitted Messages)

`chat_created`

`response_message`

`get_all_chat_messages`

`updated_chat_list`

4. Error Handling