Inbox & Channels Module Specification

1. Purpose & Overview

inbox

channels

2. Responsibilities

• Manage WebSocket connection lifecycle (

  connect

  ,

  disconnect

  ,

  receive

  ) via

  InboxConsumer

  .
• Route messages across agent connections in group

  inbox_<tenant_id>

  .
• Provide live unread count updates and agent typing indicators.

3. Directory Structure

services/api/inbox/
├── consumers.py
├── routing.py
├── views.py
└── tests/

4. Models & Database Schemas

• Uses

  messaging.Conversation

  and

  messaging.Message

  models for data persistence.

5. Services & Business Logic

• InboxConsumer.connect()

  : Authenticates user, extracts

  tenant_id

  , and subscribes socket to Redis group

  inbox_<tenant_id>

  .

• InboxConsumer.disconnect()

  : Unsubscribes socket from Redis group.

• broadcast_event(tenant_id, event_type, payload)

  : Utility service for sending events to all tenant agents.

6. Serializers & Data Transfer Objects

• Realtime WebSocket JSON Frames:

  new_message

  ,

  message_status_update

  ,

  unread_count_update

  .

7. Views & API Endpoints

• WebSocket Endpoint:

  /ws/inbox/<tenant_id>/

• GET /api/inbox/stats/

  : Retrieve active agent counts and chat queue length.

8. Permissions & Role Rules

• Operators must be authenticated and belong to the

  tenant_id

  specified in the URL path.

9. Signals & Event Listeners

• Receives events from

  messaging

  and

  webhooks

  modules for instant broadcasting.

10. Background Tasks & Celery Jobs

• None (WebSocket consumer operations run asynchronously on Daphne event loop).

11. Data Flow & External Dependencies

• Relies on

  channels_redis.core.RedisChannelLayer

  for Redis Pub/Sub backend.

12. Business Rules & Validations

• WebSockets disconnect automatically if Redis connection times out or authentication fails.

13. Sequence Diagram (Mermaid)

14. Known Limitations & Technical Debt

• Requires active Redis instance (

  CHANNEL_REDIS_URL

  ).

15. Future Improvements

• Add agent collision detection (visual indicator showing when another agent is viewing or typing a reply to the same customer).