Real-time collaborative chat

Join per-book chat rooms to discuss what you’re reading with other readers. Messages are delivered instantly over WebSocket and the full conversation history is available on join.

Every book in ReadRealm has its own chat room. When you open a book, you can join the conversation, see what other readers are saying, and send messages that appear instantly for everyone in the room. The last 50 messages are loaded automatically when you join, so you never start with an empty conversation.

Per-book rooms

Each book has a dedicated chat room — book_{bookId}.

Instant delivery

Messages are broadcast to all room members in milliseconds via Socket.IO.

Message history

The 50 most recent messages load automatically when you join.

User presence

Readers are notified when someone joins or leaves the room.

Connecting

The chat system uses Socket.IO. Connect to the ReadRealm WebSocket server before sending any events:

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000', {
  transports: ['websocket'],
});

Joining a room

Send a joinRoom event with your book ID, user ID, and username. The server adds you to the room, sends you the message history, and announces your arrival to the other readers already in the room.

Event: joinRoom

{
  "bookId": 2701,
  "userId": "user_abc123",
  "username": "Alice"
}

On join you will receive:

• A previousMessages event containing the last 50 messages in the room
• All other members in the room receive a userJoined event

Sending messages

Send a chatMessage event to post a message to the room. The server saves the message and broadcasts it to all members including the sender.

Event: chatMessage

{
  "bookId": 2701,
  "userId": "user_abc123",
  "username": "Alice",
  "content": "The opening chapter sets the atmosphere perfectly."
}

All room members receive a newMessage event with the saved message object.

Leaving a room

Send a leaveRoom event when you close the book or navigate away. The server removes you from the room and notifies the remaining members.

Event: leaveRoom

{
  "bookId": 2701,
  "username": "Alice"
}

All remaining members receive a userLeft event.

Message history

The last 50 messages for a room are returned in reverse chronological order (newest first) as a previousMessages event immediately after you join. This gives you immediate context for the ongoing conversation.

User presence

ReadRealm notifies everyone in a room when the membership changes:

• userJoined — emitted to all room members when a new reader joins
• userLeft — emitted to all remaining members when a reader leaves

Both events carry the username and a timestamp:

{
  "username": "Alice",
  "timestamp": "2026-03-27T10:00:00.000Z"
}

Event reference

Events you send

Event	Payload	Description
joinRoom	{ bookId, userId, username }	Join a book’s chat room
leaveRoom	{ bookId, username }	Leave a book’s chat room
chatMessage	{ bookId, userId, username, content }	Send a message to the room

Events you receive

Event	Payload	Description
previousMessages	Message[]	Last 50 messages, sent on join
newMessage	Message	A new message posted to the room
userJoined	{ username, timestamp }	A reader joined the room
userLeft	{ username, timestamp }	A reader left the room

Event flow diagram

Client                          Server                         Other clients
  │                               │                               │
  │──── joinRoom ─────────────────▶│                               │
  │◀─── previousMessages ──────────│                               │
  │                               │──── userJoined ───────────────▶│
  │                               │                               │
  │──── chatMessage ──────────────▶│                               │
  │◀─── newMessage ────────────────│──── newMessage ───────────────▶│
  │                               │                               │
  │──── leaveRoom ─────────────────▶│                               │
  │                               │──── userLeft ─────────────────▶│
  │                               │                               │

Room IDs are derived from the book ID using the pattern book_{bookId}. For example, book 2701 uses room book_2701. You do not need to construct this manually — just pass bookId in your events.