Chat Module Overview
The chat module is a self-contained Django app that provides direct (1:1) and group chats with real-time messaging, read status, and an optional embeddable widget.
What it provides
- Direct and group chats – One-to-one and multi-user group conversations.
- Real-time delivery – WebSockets (Django Channels) for live message and list updates.
- HTMX integration – List refresh, send message, load older messages, and widget panels use HTMX.
- Embeddable widget – Optional floating action button (FAB) and panel that can be included on any page when the user is authenticated.
Features
Detailed list of what the chat module implements.
- Direct and group chats – Create 1:1 chats by user email; create group chats with a name and multiple members.
- Per-user read status and unread counts – Tracks last read per user per chat; total unread in navbar and widget.
- Soft-delete – Users can “delete” a chat for themselves (hidden from list) without affecting others.
- Real-time delivery and presence – New messages appear live via WebSocket; room shows online count.
- Load older messages – Paginated history (e.g. “Load older”) via HTMX.
- Group admin – Create group, edit name, add/remove members, leave group, or delete group (admin only).
- Widget (FAB) – Floating button opens a panel with chat list and room view; same HTMX and WebSocket behavior as full pages.
Pages and URLs
All chat routes (under /chat/ unless you change the include prefix).
| Path | Description |
|---|---|
| "" | Chat list (main inbox page) |
| list-partial/ | HTMX fragment: chat list only (for live refresh) |
| new/ | Start a new direct chat (by email) |
| new-group/ | Create a new group chat |
| check-user/ | Look up user by email (for new chat / add member) |
| widget/ | Widget page: list view in panel |
| widget/<pk>/ | Widget page: room view for chat pk |
| <pk>/ | Full-page chat room |
| <pk>/info/ | Chat info: details and actions (leave, delete, etc.) |
| <pk>/leave/ | POST: leave group chat |
| <pk>/delete/ | POST: soft-delete chat for current user |
| <pk>/delete-group/ | POST: hard-delete group (admin only) |
| <pk>/edit/ | Edit group (name, add/remove members) |
| <pk>/messages/ | GET: HTMX fragment for older messages (?before=id) |
| <pk>/send/ | POST: send message; returns message bubble fragment |
Templates and Widgets
Full-page templates and HTMX partials used by the chat module.
Full pages
Located under chat/templates/chat/.
chat_list.html– Inbox: list of chats, modals for new direct/group chat.room.html– Single chat room (messages, send form, load older).new_chat.html– Standalone new direct chat (optional).edit_group.html– Edit group name and members.chat_info.html– Chat details and actions (leave, delete group, etc.).chat_widget.html– Standalone widget page (FAB + panel with list/room).
Partials (HTMX)
Located under chat/templates/chat/partials/.
chat_list_fragment.html– Rendered for list refresh (list page and widget).message_bubble.html– Single message; returned after send.message_list_fragment.html– Block of older messages for “load older”.new_chat_form.html– Form for new direct chat (e.g. in modal).new_group_chat_form.html– Form for new group (name + members).widget_info.html– Chat info inside widget panel.widget_response_room.html– Room content inside widget panel.widget_response_list.html– List content inside widget panel.check_user_result.html– Result of email lookup (e.g. “User found” / “Not found”).
How to integrate the chat module
Steps to copy the chat app into another Django project and wire it up.
1. Copy the chat app
Copy the entire chat directory into your project (e.g. alongside your other apps). It includes:
- models, views, urls, admin, consumers, routing, context_processors
- templates (chat/templates/chat/ and partials/)
- migrations and management commands (e.g. seed_chat_data, purge_deleted_chats)
2. Django settings and URLs
- Add
'channels'and'chat'toINSTALLED_APPS. - Include chat URLs:
path('chat/', include('chat.urls'))(or your preferred prefix). - Add the chat context processor so the widget gets list data and unread count:
'chat.context_processors.chat_widget'inTEMPLATES[0]['OPTIONS']['context_processors'].
3. ASGI and WebSocket
Run the app with an ASGI server (e.g. Daphne or Uvicorn). In your ASGI module:
- Mount HTTP (Django) and WebSocket; WebSocket routing must include
chat.routing.websocket_urlpatternssows/chat/inbox/andws/chat/<id>/are handled. - Set
ASGI_APPLICATIONto your ASGI callable. - Configure
CHANNEL_LAYERS: Redis (channels_redis) for production, orInMemoryChannelLayerfor development.
4. Static files
Chat relies on these JS (and any chat-specific CSS) being available. This project keeps them in the main app static/js/components/chat/ (e.g. widget.js, chat-websocket.js, chat-inbox.js, message-send.js). Ensure your host app serves or collects these; load them where needed (e.g. base template for FAB/inbox, widget page for widget).
5. Auth and user model
Chat requires authenticated users. The host app must use Django’s auth (or compatible) so request.user is available. The chat app uses get_user_model() and expects users to have at least username and email (or equivalent); document or adjust if your project uses a custom user with different fields.
WebSocket endpoints
The chat module exposes two WebSocket routes (from chat/routing.py).
- ws/chat/inbox/ – Inbox consumer. Each authenticated user connects to receive list updates (new messages, unread counts, list refresh) and total unread for the FAB/navbar.
- ws/chat/<chat_id>/ – Room consumer. Clients connect when viewing a room to receive new messages and presence (online count); also used to mark the room as read and update total unread.