Chat WebSocket Documentation

1. Overview

The Chat WebSocket system enables real-time communication between users. The system provides:

• Real-time text messaging
• File attachments (images, videos, documents, audio)
• Direct chat rooms between users
• Typing indicators
• Online/offline status
• Read receipts
• Message history
• Unread message counts

2. Architecture

2.1 Components

• WebSocket Consumer: ChatConsumer handles WebSocket connections
• Channel Layer: Redis-based message broadcasting
• Django Channels: ASGI framework for WebSocket support
• JWT Authentication: Token-based authentication middleware

2.2 Flow Diagram

User → WebSocket Connection → JWT Auth → Participant Check → Join Group → Ready
                                                                    ↓
User sends message → Save to DB → Broadcast to Group → All participants receive
        

3. Authentication

WebSocket connections require JWT authentication. The token must be provided in one of two ways:

3.1 Query String (Recommended)

3.2 Authorization Header

Some WebSocket clients support custom headers:

Authorization: Bearer {{jwt_token}}

4. Understanding Room ID

4.1 What is Room ID?

The room_id is the unique identifier (primary key) of a ChatRoom instance. It's a numeric value that uniquely identifies a chat room between users. You need the room_id to:

• Send messages in a specific chat room
• Connect to the WebSocket for real-time messaging
• Get room details and message history
• Mark messages as read

4.2 How to Get Room ID

Method 1: Create a New Chat Room

When you create a direct chat, the response includes the room_id:

{
    "user_id": 123
}

{
    "id": 456,  // ← This is the room_id
    "participants": [
        {"id": 1, "username": "current_user"},
        {"id": 123, "username": "other_user"}
    ],
    "is_group": false,
    "created_at": "2024-03-20T10:00:00Z",
    "unread_count": 0
}

Note: If a chat room already exists between you and the specified user, the existing room is returned (no new room is created).

Method 2: List Your Chat Rooms

Get all chat rooms you're part of. Each room in the list has an id field:

{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 456,  // ← room_id
            "participants": [
                {"id": 1, "username": "user1"},
                {"id": 123, "username": "user2"}
            ],
            "last_message": {
                "id": 789,
                "content": "Hello!",
                "created_at": "2024-03-20T10:00:00Z"
            },
            "unread_count": 3,
            "is_group": false
        },
        {
            "id": 789,  // ← another room_id
            "participants": [...],
            "last_message": Ellipsis,
            "unread_count": 0,
            "is_group": false
        }
    ]
}

Method 3: Get Specific Room Details

If you already know the room_id, you can fetch that room's details directly:

4.3 Using Room ID

Once you have the room_id, you can use it for various operations:

Send a Message

{
    "content": "Hello, this is a test message!"
}

Get Room Messages

Mark Messages as Read

Connect to WebSocket

4.4 Complete Example: Getting and Using Room ID

// Step 1: Create or get chat room
const response = await fetch('http://localhost:8000/api/chats/', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        user_id: 123
    })
});

const room = await response.json();
const roomId = room.id;  // Extract room_id
console.log('Room ID:', roomId);

// Step 2: Use room_id to send a message
await fetch(`http://localhost:8000/api/chats/${roomId}/messages/`, {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        content: 'Hello!'
    })
});

// Step 3: Connect to WebSocket using room_id
const ws = new WebSocket(
    `ws://localhost:8000/ws/chat/${roomId}/?token=${token}`
);

5. WebSocket Connection

5.1 Connection URL

5.2 Connection Requirements

• User must be authenticated (valid JWT token)
• User must be a participant in the chat room
• Chat room must exist and be accessible

5.3 Connection Status Codes

6. WebSocket Events

All WebSocket messages are JSON objects with a type field that identifies the event type. This section documents all events you can send (trigger) and all events you will receive (listen to).

6.1 Events to Trigger (Send to Server)

These are events you send to the server via WebSocket:

6.1.1 Send Chat Message

{
    "type": "chat_message",
    "content": "Your message text here"
}

{
    "type": "chat_message",
    "content": "Check out this image!",
    "attachment_url": "https://example.com/files/image.jpg",
    "attachment_type": "image",
    "attachment_name": "image.jpg"
}

{
    "type": "chat_message",
    "content": "Here's a small image",
    "attachment_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "attachment_type": "image",
    "attachment_name": "photo.jpg"
}

6.1.2 Send Typing Indicator

{
    "type": "typing"
}

6.1.3 Send Read Receipt

{
    "type": "read_receipt",
    "message_id": "123"
}

6.2 Events to Listen (Receive from Server)

These are events you receive from the server via WebSocket:

6.2.1 Receive Chat Message

{
    "type": "chat_message",
    "content": "Message content",
    "user_id": 7,
    "username": "john_doe",
    "full_name": "John Doe",
    "message_id": "123",
    "timestamp": "2025-11-15T18:23:21.483664+00:00"
}

{
    "type": "chat_message",
    "content": "Check out this image!",
    "user_id": 7,
    "username": "john_doe",
    "full_name": "John Doe",
    "message_id": "123",
    "timestamp": "2025-11-15T18:23:21.483664+00:00",
    "attachment_url": "https://api.qsocial.net/media/chat/attachments/abc123.jpg",
    "attachment_type": "image",
    "attachment_name": "photo.jpg",
    "attachment_size": 245678
}

6.2.2 User Online Event

{
    "type": "user_online",
    "user_id": 7,
    "username": "john_doe",
    "full_name": "John Doe"
}

6.2.3 User Offline Event

{
    "type": "user_offline",
    "user_id": 7,
    "username": "john_doe"
}

6.2.4 User Typing Event

{
    "type": "user_typing",
    "user_id": 7,
    "username": "john_doe",
    "full_name": "John Doe"
}

6.2.5 Message Read Event

{
    "type": "message_read",
    "message_id": "123",
    "user_id": 7,
    "username": "john_doe"
}

6.2.6 Error Event

{
    "type": "error",
    "message": "Error processing message"
}

6.3 Event Flow Summary

7. REST API Endpoints

7.1 List Chat Rooms

7.2 Create Direct Chat

{
    "user_id": 123,
    "post_id": 456  // Optional: if chat initiated from a post
}

7.3 Get Chat Room Details

7.4 Send Message (HTTP)

{
    "content": "Your message here"
}

Content-Type: multipart/form-data

content: "Check out this image!"
attachment: [file binary data]

{
    "id": 123,
    "sender": {
        "id": 7,
        "username": "john_doe",
        "full_name": "John Doe"
    },
    "content": "Check out this image!",
    "created_at": "2025-11-15T18:23:21.483664+00:00",
    "is_read": false,
    "attachment_url": "https://api.qsocial.net/media/chat/attachments/abc123.jpg",
    "attachment_type": "image",
    "attachment_name": "photo.jpg",
    "attachment_size": 245678
}

7.5 Delete Message

7.6 Mark Messages Read

8. Error Handling

8.1 Connection Errors

8.2 Message Errors

8.3 Reconnection Strategy

// Exponential backoff reconnection
let reconnectAttempts = 0;
const maxReconnectAttempts = 5;

function reconnect() {
  if (reconnectAttempts >= maxReconnectAttempts) {
    console.error('Max reconnection attempts reached');
    return;
  }

  const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
  reconnectAttempts++;

  setTimeout(() => {
    console.log(`Reconnecting (attempt ${reconnectAttempts})...`);
    connect();
  }, delay);
}

9. Code Examples

9.1 Complete JavaScript Example

class ChatService {
  constructor(jwtToken, roomId) {
    this.jwtToken = jwtToken;
    this.roomId = roomId;
    this.ws = null;
    this.onMessageCallback = null;
    this.onUserOnlineCallback = null;
    this.onUserOfflineCallback = null;
  }

  connect() {
    const url = `wss://api.qsocial.net/ws/chat/${this.roomId}/?token=${this.jwtToken}`;
    this.ws = new WebSocket(url);

    this.ws.onopen = () => {
      console.log('Connected to chat');
    };

    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      this.handleMessage(data);
    };

    this.ws.onerror = (error) => {
      console.error('WebSocket error:', error);
    };

    this.ws.onclose = (event) => {
      console.log('Connection closed:', event.code, event.reason);
      // Implement reconnection logic here
    };
  }

  handleMessage(data) {
    switch (data.type) {
      case 'chat_message':
        if (this.onMessageCallback) {
          this.onMessageCallback(data);
        }
        break;
      case 'user_online':
        if (this.onUserOnlineCallback) {
          this.onUserOnlineCallback(data);
        }
        break;
      case 'user_offline':
        if (this.onUserOfflineCallback) {
          this.onUserOfflineCallback(data);
        }
        break;
      case 'user_typing':
        if (this.onUserTypingCallback) {
          this.onUserTypingCallback(data);
        }
        break;
      case 'message_read':
        if (this.onMessageReadCallback) {
          this.onMessageReadCallback(data);
        }
        break;
      case 'error':
        if (this.onErrorCallback) {
          this.onErrorCallback(data);
        }
        break;
    }
  }
  
  sendReadReceipt(messageId) {
    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({
        type: 'read_receipt',
        message_id: messageId
      }));
    }
  }

  sendMessage(content) {
    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({
        type: 'chat_message',
        content: content
      }));
    }
  }

  sendTyping() {
    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({
        type: 'typing'
      }));
    }
  }

  disconnect() {
    if (this.ws) {
      this.ws.close();
      this.ws = null;
    }
  }
}

// Usage
const chat = new ChatService('your_jwt_token', 123);
chat.onMessageCallback = (data) => {
  console.log('New message:', data);
  // Update UI
};
chat.connect();

Chat WebSocket Documentation
Last Updated: September 12, 2026
API Version: 1.0