Messaging Module Specification

1. Purpose & Overview

messaging

2. Responsibilities

• Maintain

  Conversation

  and

  Message

  domain models.
• Track message status (

  QUEUED

  ,

  SENT

  ,

  DELIVERED

  ,

  READ

  ,

  FAILED

  ).
• Store media attachments and WhatsApp Message IDs (

  wamid

  ).

3. Directory Structure

services/api/messaging/
├── admin.py
├── apps.py
├── migrations/
├── models.py
├── serializers.py
└── views.py

4. Models & Database Schemas

class MessageDirection(models.TextChoices):
    INBOUND = 'INBOUND', 'Inbound'
    OUTBOUND = 'OUTBOUND', 'Outbound'

class MessageStatus(models.TextChoices):
    QUEUED = 'QUEUED', 'Queued'
    SENT = 'SENT', 'Sent'
    DELIVERED = 'DELIVERED', 'Delivered'
    READ = 'READ', 'Read'
    FAILED = 'FAILED', 'Failed'

class Conversation(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    tenant = models.ForeignKey('tenants.Tenant', on_delete=models.CASCADE)
    customer_phone = models.CharField(max_length=20, db_index=True)
    customer_name = models.CharField(max_length=150, blank=True)
    last_message_at = models.DateTimeField(auto_now=True)

class Message(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    conversation = models.ForeignKey(Conversation, on_delete=models.CASCADE, related_name='messages')
    wamid = models.CharField(max_length=255, blank=True, db_index=True)
    direction = models.CharField(max_length=10, choices=MessageDirection.choices)
    content = models.TextField(blank=True)
    status = models.CharField(max_length=20, choices=MessageStatus.choices, default=MessageStatus.QUEUED)
    created_at = models.DateTimeField(auto_now_add=True)

5. Services & Business Logic

• Message.update_status(new_status)

  : Updates status and publishes WebSocket event to

  inbox_<tenant_id>

  channel group.

6. Serializers & Data Transfer Objects

• MessageSerializer

  : Serializes message data, direction, and timestamps.

• ConversationSerializer

  : Includes last message snippet and unread counts.

7. Views & API Endpoints

• GET /api/conversations/

  : List active customer conversations.

• GET /api/conversations/{id}/messages/

  : Retrieve message history.

• POST /api/conversations/{id}/send/

  : Send outbound message.

8. Permissions & Role Rules

• TENANT_ADMIN

  &

  TENANT_USER

  : Access conversations belonging to their tenant.

9. Signals & Event Listeners

• post_save

  on

  Message

  : Triggers realtime WebSocket notification to agent inbox.

10. Background Tasks & Celery Jobs

• Outbound API calls executed asynchronously via Celery worker queue.

11. Data Flow & External Dependencies

• Integrates with Meta WhatsApp Graph API (

  v22.0

  ) for outbound message dispatch and status updates.

12. Business Rules & Validations

• Outbound messages must specify a valid destination phone number in E.164 format.

13. Sequence Diagram (Mermaid)

14. Known Limitations & Technical Debt

• Media attachments currently stored on local disk in dev mode (

  media/

  ).

15. Future Improvements

• Migration to AWS S3 / Cloudflare R2 object storage for media attachments.