Communications Module

The Communications module handles real-time messaging between agents and end-users across Meta platforms (WhatsApp, Messenger, Instagram). It is a bounded context within the API that owns Conversations, Messages, and ChannelAccounts.

Capabilities

Capability	Status	Description
Inbound messaging	active	Receive Meta webhook events and persist incoming messages
Outbound messaging	active	Send text replies from agents via POST /conversations/:id/messages
Delivery status tracking	active (WA only)	Receive WhatsApp delivery/read/failed status webhooks and update Message state
ChannelAccount management	active	Manage Meta channel integrations (WA phone numbers, FB Pages, IG accounts)

Module Boundaries

The Communications module resides at apps/api/src/modules/communications/ and follows the project's Hexagonal/Screaming Architecture convention:

communications/
  application/
    commands/          — CQRS command handlers
    queries/           — CQRS query handlers
    errors/            — Typed domain error factories
  domain/
    entities/          — Message, Conversation, ChannelAccount aggregates
    policies/          — Business rules (e.g. per-channel text limits)
    repositories/      — Repository interfaces (ports)
  infrastructure/
    persistence/       — TypeORM entities, mappers, repository implementations
    migrations/        — Additive SQL migrations
  presentation/
    controllers/       — NestJS REST controllers

Key Entities

• Conversation — thread between an org and a single end-user contact on a specific ChannelAccount. Tracks customerCareWindowExpiresAt for WhatsApp 24h window enforcement.
• Message — single message in a conversation. Has direction (inbound | outbound), deliveryStatus (pending → sent → delivered → read | failed), externalMessageId, and tempId.
• ChannelAccount — org-specific Meta channel config (phone number, page, IG account). Must be status='active' for outbound sends.

API Surface

Method	Path	Description
GET	/conversations	Paginated list of conversations (tenant-scoped)
GET	/conversations/:id	Single conversation by id
GET	/conversations/:id/messages	Paginated messages for a conversation
POST	/conversations/:id/messages	NEW — Send outbound text message
POST	/meta-webhook	Meta webhook receiver (inbound messages + status events)
GET/POST/DELETE	/channel-accounts/*	ChannelAccount CRUD

CASL Subjects

Subject	Description
communications.message	Read/create messages
communications.conversation	Read/manage conversations
communications.channel-account	Manage channel integrations

Integration Events

Published after successful operations (EventBus, in-process):

Event	Trigger
OutboundMessageSentIntegrationEvent	Agent message successfully sent and persisted
MessageDeliveryStatusChangedIntegrationEvent	WA delivery/read/failed status webhook processed
IncomingMetaMessageReceivedIntegrationEvent	Inbound message webhook received

Feature Docs

• Outbound Messaging — POST /conversations/:id/messages, idempotency, WA 24h window, per-channel limits, error catalog
• Delivery Status Tracking — state machine, WA webhook pipeline, integration event payloads