Skip to content

Documentation for Real-Time Chat App

Overview

This document provides an explanation of the WebSocket views implemented for the chat functionality in the ChatConsumer and AllChatConsumer classes. The WebSocket connections are established via Django Channels, enabling real-time communication between users. Below are the endpoints, permissions, and actions supported by the implementation.

WebSocket Actions

1. Chat Consumer

  • Endpoint: /v1/ws/chat/<str:chat_id>/
  • Method: WebSocket
  • Description: Connects to a specific chat room using the chat_id parameter, allowing users to send and receive real-time messages.

2. All Chat Consumer

  • Endpoint: /v1/ws/chats/
  • Method: WebSocket
  • Description: Connects to a general chat room for all chats, allowing users to receive updates and send messages across multiple chats.

Permissions

Authentication via JWT

  • Authentication is handled by the custom middleware JWTAuthMiddleware.
  • Users must provide a valid JWT token as a query parameter, e.g., ?token=some_token_here.
  • Tokens are verified and decoded to extract the user ID. If the token is invalid or expired, the connection is rejected.

Participant Validation

  • Only participants of the specified chat (either the user or the vendor or vendor role) are allowed to join the chat room. Unauthorized users are disconnected.

Actions Supported

1. Ping

  • Action: ping
  • Description: Keeps the WebSocket connection alive. The server ignores this action without sending a response.

2. Load Latest Chat

  • Action: load_latest_chat
  • Description:
  • Automatically triggered upon connection.
  • Loads all previous messages from the chat and sends them to the client.
  • Each message includes details such as sender, receiver, content, media type, timestamps, and whether the message has been read.

3. Send Message

  • Action: send_message
  • Parameters:
  • content (optional): The text message to send.
  • receiver_id: The ID of the user receiving the message.
  • media_type: The type of media being sent (text, image, audio, or video).
  • image (optional): Base64-encoded image data.
  • audio (optional): Base64-encoded audio data.
  • video (optional): Base64-encoded video data.
  • Description:
  • Sends a new message to the chat.
  • Broadcasts the message to all participants in the chat room.
  • Only one of content, image, audio, or video is required.
  • Validation ensures that the sender and receiver are valid participants of the chat.

4. Read Message

  • Action: read_message
  • Parameters:
  • message_id: The ID of the message to mark as read.
  • Description:
  • Marks the specified message as read if the current user is the recipient.
  • Broadcasts the updated read status to all participants in the chat room.

5. Delete Message

  • Action: delete_message
  • Parameters:
  • message_id: The ID of the message to delete.
  • Description:
  • Deletes the specified message from the database.
  • Broadcasts a message_deleted event to all participants in the chat room.

6. Receive Unread Messages

  • Action: unread_message
  • Description:
  • Triggered automatically whenever a new message is sent.
  • Sends all unread messages in the chat to the client.
  • Includes detailed information for each unread message.

Events

chat_message

  • Triggered when a new message is sent in the chat room.
  • Broadcasts the message details to all participants.

message_read

  • Triggered when a message is marked as read.
  • Broadcasts the updated read status to all participants.

message_deleted

  • Triggered when a message is deleted.
  • Broadcasts the message deletion event to all participants.

Explanation of Key Components

ChatConsumer Class

  • Handles WebSocket connections for real-time chat.
  • Each instance of the consumer corresponds to a unique WebSocket connection.

AllChatConsumer Class

  • Handles WebSocket connections for all chats.
  • Allows users to receive updates and send messages across multiple chats.

Connect Method

  • Authenticates the user via JWT.
  • Validates that the user is a participant in the chat.
  • Loads previous messages and sends unread messages.

Receive Method

  • Parses incoming JSON payloads and routes actions to the appropriate handlers (e.g., send_message, read_message).

Database Interactions

  • Utilizes Django ORM and @database_sync_to_async decorators to perform database operations asynchronously.
  • Interactions include retrieving chats, fetching messages, and saving updates to the database.

Usage Example

Connecting to a Chat Room

  • To connect to a specific chat room, use the following WebSocket URL:

ws://localhost:8000/v1/ws/chat//?token=

Sending a Message

  • To send a message, send a JSON payload with the action send_message: 
    {
    "action": "send_message",
    "content": "Hello, how are you?",
    "receiver_id": "123",
    "media_type": "text"
}

Marking a Message as Read

To mark a message as read, send a JSON payload with the action read_message: 

{
  "action": "read_message",
  "message_id": "456"
}

Deleting a Message

To delete a message, send a JSON payload with the action delete_message: 

{
  "action": "delete_message",
  "message_id": "456"
}