Chat

Real-time book discussion rooms powered by WebSockets. Messages are persisted to MongoDB and replayed when a user joins a room.

ReadRealm’s chat feature lets readers discuss any book in real time. Each book has its own chat room identified by bookId. Chat is primarily WebSocket-based — there are no REST endpoints for sending or receiving messages live.

For the full WebSocket event reference (joining rooms, sending messages, receiving broadcasts), see WebSockets.

How it works

When a user connects to a chat room over WebSocket:

1. The client emits a joinRoom event with a bookId.
2. The server calls ChatService.getRoomMessages(bookId) and immediately emits the last 50 messages back to the joining client.
3. Subsequent messages sent in the room are broadcast to all connected clients in real time.
4. Every message emitted by a client is persisted to MongoDB via ChatService.saveMessage().

This means all chat history survives server restarts and is available to new participants.

Message persistence

Messages are stored in MongoDB using the Message schema. The service exposes two operations used internally by the WebSocket gateway:

• saveMessage(message) — persists a new message.
• getRoomMessages(bookId) — retrieves the last 50 messages for a room, sorted by createdAt descending.

Message object

All chat messages share the following structure:

bookId · number · required

Numeric ID of the book whose room this message belongs to. Matches the id field in the Books API.

userId · string · required

ID of the user who sent the message. Matches the _id field in the Users API.

username · string · required

Display name of the sender at the time the message was sent.

content · string · required

Text body of the message.

createdAt · string

ISO 8601 timestamp added automatically by MongoDB (timestamps: true).

updatedAt · string

ISO 8601 timestamp of last modification, added automatically by MongoDB.

Example message payload

{
  "bookId": 28520,
  "userId": "64a1f3c2e4b0a1234567890a",
  "username": "alice",
  "content": "The Cheshire Cat scene is my favourite!",
  "createdAt": "2024-03-15T14:32:00.000Z",
  "updatedAt": "2024-03-15T14:32:00.000Z"
}

Room history on join

When a client joins a room, the server replays history. The client receives a previousMessages event containing an array of up to 50 recent messages in the room, ordered newest-first.

This lets a user who joins mid-conversation catch up on context without any additional API calls.

Continue reading

WebSocket reference

Full event names, payloads, and connection flow for the real-time chat gateway.