Skip to content

Chat Views Documentation

Overview

This document explains the functionality of the ChatViewSet and MessageViewSet classes used to manage chat conversations and messages in the API. These viewsets enable operations such as listing chats, sending messages, marking messages as read, and deleting messages. The base URL for these endpoints is api/v1/chat/.

Endpoints and Actions

ChatViewSet

Endpoint HTTP Method Action Description Permissions
api/v1/chat/ GET list List all chats for the authenticated user HasVendorRolePermission
api/v1/chat/ POST create Create a new chat HasVendorRolePermission
api/v1/chat/<str:pk>/ GET retrieve Retrieve details of a specific chat HasVendorRolePermission

MessageViewSet

Endpoint HTTP Method Action Description Permissions
api/v1/chat/send/message POST send_message Send a message in a chat IsAuthenticated
api/v1/chat/detail/message/<str:pk>/ GET retrieve Retrieve details of a specific message IsAuthenticated
api/v1/chat/read/message/<str:pk>/ PATCH read_message Mark a message as read IsAuthenticated
api/v1/chat/delete/message/<str:pk>/ DELETE destroy Delete a message IsAuthenticated

ChatViewSet Explanation

1. Permissions

The ChatViewSet requires the user to have the Chat Management role to access these views, which is enforced by the custom permission class HasVendorRolePermission.

2. list

  • Purpose: Retrieves all chats associated with the authenticated user, sorted by the latest message timestamp.
  • Implementation:
  • Filters chats where the user is either the chat's user or the vendor.
  • Prefetches the latest messages in each chat and sorts the chats accordingly.
  • Utilizes a custom pagination class to paginate the response.

3. create

  • Purpose: Creates a new chat between a user and a vendor.
  • Additional Behavior:
  • A welcome message is automatically sent by the vendor to the user upon chat creation.
  • A WebSocket notification is sent to the vendor, instructing them to reload unread messages.
  • Validation: Ensures the user and vendor are distinct and exist in the database.

4. retrieve

  • Purpose: Retrieves details of a specific chat identified by its primary key (pk).
  • Behavior:
  • Returns serialized chat data if the chat exists.
  • Checks if the authenticated user has permission to access the chat (either as the user or the vendor).
  • Raises a 403 error if the user is not authorized to view the chat.
  • Raises a 404 error if the chat is not found.

MessageViewSet Explanation

1. Permissions

The MessageViewSet dynamically assigns permissions based on the action being performed. All actions require the user to be authenticated.

2. send_message

  • Purpose: Sends a new message in a specific chat.
  • Validation:
  • Ensures the sender and receiver are not the same user.
  • Ensures the user has permission to send a message in the specified chat.
  • Creates the message and returns a success response with the message data.
  • Returns a 404 error if the sender and receiver are the same.

3. retrieve

  • Purpose: Retrieves details of a specific message identified by its primary key (pk).
  • Behavior:
  • Returns serialized message data if the message exists.
  • Raises a 404 error if the message is not found.

4. read_message

  • Purpose: Marks a specific message as read.
  • Validation:
  • Ensures the is_read field is updated to True.
  • Returns the updated message data if the validation succeeds.
  • Returns a 400 error if the is_read field is not set to True.

5. destroy

  • Purpose: Deletes a specific message identified by its primary key (pk).
  • Behavior:
  • Deletes the message if it exists.
  • Returns a success response if the deletion is successful.
  • Raises a 404 error if the message is not found.

Summary

The ChatViewSet and MessageViewSet provide a comprehensive set of actions to manage chat conversations and messages in the API. Permissions are dynamically assigned to ensure security, and custom behaviors such as automatic welcome messages and WebSocket notifications for vendors enhance user experience. Each endpoint is tailored to handle specific actions, ensuring a clear and structured API design.