Real-Time Chat System API Documentation

This documentation outlines how to consume the WebSocket API for the 1-on-1 chat system.

Prerequisites

You need a WebSocket client to connect to the server. We recommend using socket.io-client.

npm install socket.io-client

Connection

Connect to the server URL (default: http://localhost:3000).

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

const socket = io("http://localhost:3000");

socket.on("connect", () => {
  console.log("Connected to chat server:", socket.id);
  // Register user for notifications
  socket.emit("register_user", "uuid-string-of-current-user");
});

WebSocket Events

1. Register User (Required for Notifications)

Joins the user to a personal channel to receive real-time updates like chat_list_update.

Emit: register_user

Payload: uuid-string-of-current-user

---

2. Join a Chat

Initiates a chat session between two users. The server automatically determines the unique room for these two users.

Emit: join_chat

Payload:

{
  userId: "uuid-string-of-current-user",
  targetUserId: "uuid-string-of-other-user"
}

Responses:

• Success (room_joined): Returns the room details.

  socket.on("room_joined", (data) => {
    console.log("Room ID:", data.roomId);
    console.log("Room Details:", data.room);
  });

• History (message_history): Returns the last 50 messages immediately after joining.

  socket.on("message_history", (data) => {
    console.log("Messages:", data.messages); // Array of message objects
  });

• Error (error): If validation fails.

  socket.on("error", (err) => {
    console.error("Error:", err.message);
  });

---

3. Send a Message

Sends a message to the current room.

Emit: send_message

Payload:

{
  roomId: "uuid-of-the-room", // Obtained from 'room_joined' event
  senderId: "uuid-string-of-current-user",
  body: "Hello world!"
}

Responses:

• Success (new_message): Broadcasted to both participants in the room. Use this to append the message to the UI.

  socket.on("new_message", (message) => {
    console.log("New Message:", message);
    // {
    //   id: "uuid...",
    //   room_id: "...",
    //   sender_id: "...",
    //   body: "Hello world!",
    //   created_at: "2023-10-27T..."
    // }
  });

• Update (chat_list_update): Sent to the receiver to update their chat list preview in real-time.

  socket.on("chat_list_update", (data) => {
     console.log("Chat List Update:", data);
     // { 
     //   room_id: "uuid...", 
     //   last_message: "Hello world!", 
     //   sender_id: "uuid...", 
     //   updated_at: "timestamp..." 
     // }
  });

---

4. Fetch Older Messages (Pagination)

Load previous messages when the user scrolls up.

Emit: fetch_messages

Payload:

{
  roomId: "uuid-of-the-room",
  limit: 20,   // Number of messages to fetch (default: 20)
  offset: 50   // Number of messages already loaded (e.g., current list length)
}

Responses:

• Success (more_messages):

  socket.on("more_messages", (data) => {
    const olderMessages = data.messages; // Prepend these to your UI list
    const nextOffset = data.offset;      // Use this for the next fetch
    
    if (olderMessages.length === 0) {
      console.log("No more messages.");
    }
  });

Data Structures

Room Object

{
  "id": "uuid-room-id",
  "participant1": "uuid-user-a",
  "participant2": "uuid-user-b",
  "created_at": "timestamp",
  "updated_at": "timestamp",
  "last_message_at": "timestamp"
}

Message Object

{
  "id": "uuid-message-id",
  "room_id": "uuid-room-id",
  "sender_id": "uuid-sender-id",
  "body": "Message content",
  "created_at": "timestamp"
}

Example Integration Flow

// 1. Initialize
const currentUser = "user-uuid-1";
const otherUser = "user-uuid-2";
let currentRoomId = null;

// 2. Join Chat
socket.emit("join_chat", { userId: currentUser, targetUserId: otherUser });

// 3. Handle Room Join
socket.on("room_joined", ({ roomId }) => {
  currentRoomId = roomId;
  console.log("Joined room:", roomId);
});

// 4. Handle Initial Messages
socket.on("message_history", ({ messages }) => {
  renderMessages(messages); // Render initial list
});

// 5. Send Message
function sendMessage(text) {
  if (!currentRoomId) return;
  socket.emit("send_message", {
    roomId: currentRoomId,
    senderId: currentUser,
    body: text
  });
}

// 6. Receive Real-time Messages
socket.on("new_message", (message) => {
  appendMessage(message);
});