The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
Messaging Plugin Documentation
Buyer-vendor messaging system with real-time SSE delivery, content filtering, admin oversight, chat blocking, GDPR erasure, cursor-based pagination, and dashboard UI for both vendor and admin panels.
Table of Contents
- Architecture Overview
- Installation & Configuration
- Modules
- Data Models
- Module Links
- Workflows
- API Reference — Store (Customer)
- API Reference — Vendor (Seller)
- API Reference — Admin
- SSE Real-Time Event System
- Cursor-Based Pagination
- Content Filtering
- Rate Limiting
- Context Linking
- Unread Tracking
- GDPR & Data Privacy
- Chat Blocking
- Event Subscribers
- Scheduled Jobs
- Error Reference
- Testing
- Configuration Reference
Architecture Overview
┌─────────────────────────────────────────────────────────────────────┐
│ API Layer │
│ Store (Customer) Vendor (Seller) Admin │
│ /store/messages/* /vendor/messages/* /admin/messages/*│
└──────────┬─────────────────────┬────────────────────────┬───────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Workflows │
│ send-message │ create-conversation │ mark-messages-read │
│ anonymize-buyer │ anonymize-vendor │ filter-rule CRUD │
│ block-customer │ unblock-customer │
└──────────┬──────────────────────────────────────────────────────────┘
│
▼
┌────────────────────┐ ┌─────────────────────┐ ┌──────────────────┐
│ Messaging Module │ │ Messaging Filters │ │ Messaging Redis │
│ - Conversation │ │ - FilterRule │ │ - Pub/Sub │
│ - Message │ │ - BlockedMessageLog │ │ - Rate Limiting │
│ - ChatBlock │ │ - Evaluation │ │ - SSE Tokens │
│ - CRUD + Cursors │ │ │ │ │
└────────────────────┘ └─────────────────────┘ └──────────────────┘
│ │
▼ ▼
PostgreSQL Redis
The plugin follows Medusa's architecture strictly:
- Modules handle data access and CRUD operations only
- Workflows contain all business logic, validation, and side effects
- API Routes handle HTTP concerns, delegate to workflows
- Subscribers react to domain events asynchronously
- Scheduled Jobs perform periodic maintenance
Three actor types interact with the system:
| Actor | Auth Method | Capabilities |
|---|---|---|
| Customer (Buyer) | Session / Bearer | Create conversations, send messages, mark read, SSE via token |
| Seller (Vendor) | Session / Bearer | List conversations, reply, mark read, SSE via session |
| Admin | Session / Bearer | Search all conversations, manage filters, view blocked messages, block/unblock customers, SSE (all events) |
Installation & Configuration
Install the block
mercurjs add messaging
Dependencies
| Dependency | Purpose |
|---|---|
ioredis |
Redis client for pub/sub, rate limiting, SSE tokens |
Redis is optional but strongly recommended. Without it, SSE, rate limiting, and notification throttling are disabled. Core REST messaging (send, receive, mark read) and content filtering continue to work.
Environment variables
REDIS_URL=redis://localhost:6379
Module registration
// medusa-config.ts
module.exports = defineConfig({
modules: [
{ resolve: "./modules/messaging" },
{ resolve: "./modules/messaging-filters" },
{
resolve: "./modules/messaging-redis",
options: { redisUrl: process.env.REDIS_URL },
},
],
})
Run migrations
npx medusa db:migrate
This creates the conversation, message, chat_block, filter_rule, and blocked_message_log tables.
Modules
Messaging Module
Identifier: messaging
Core module handling conversations and messages. Provides cursor-based pagination, atomic message creation, and atomic read marking.
Service: MessagingModuleService
// Cursor-paginated conversation listing
listConversationsCursor(
filter: { buyer_id?: string; seller_id?: string },
pagination: { cursor?: string; limit?: number }
): Promise<{ data: ConversationDTO[]; next_cursor: string | null }>
// Cursor-paginated message listing (descending order)
listMessagesCursor(
conversationId: string,
pagination: { cursor?: string; limit?: number }
): Promise<{ data: MessageDTO[]; next_cursor: string | null }>
// Admin search with filtering across seller/buyer names, dates, context
searchConversationsAdmin(
filter: {
seller_name?: string; buyer_name?: string;
date_from?: string; date_to?: string;
context_type?: string; context_id?: string
},
pagination: { cursor?: string; limit?: number }
): Promise<{ data: ConversationDTO[]; next_cursor: string | null }>
// Total unread count across all conversations for a user
getUnreadCountTotal(
filter: { buyer_id?: string; seller_id?: string }
): Promise<number>
// Atomic: creates message + updates conversation metadata + increments unread
createMessageAtomic(data: {
conversation_id: string; sender_id: string; sender_type: SenderType;
body: string; context_type?: string; context_id?: string; context_label?: string;
}): Promise<MessageDTO>
// Atomic: marks opposite-party messages as read + resets unread counter
markMessagesReadAtomic(
conversationId: string,
readerType: "customer" | "seller"
): Promise<number> // count of messages marked
// Cursor encoding/decoding
encodeCursor(values: Record<string, string | number | null>): string
decodeCursor(cursor: string): Record<string, string | number | null> | null
// Batch check which buyer IDs are chat-blocked (single WHERE IN query)
checkBuyersBlocked(
buyerIds: string[]
): Promise<Set<string>>
Also inherits standard MedusaService CRUD methods: listConversations, createConversations, updateConversations, deleteConversations, listMessages, createMessages, updateMessages, deleteMessages, listChatBlocks, createChatBlocks, deleteChatBlocks.
Messaging Filters Module
Identifier: messagingFilters
Manages content filter rules and blocked message logging. Compiles rules into an optimized in-memory structure for fast evaluation.
Service: MessagingFiltersModuleService
// Evaluate a message body against the compiled ruleset
evaluateMessage(
body: string,
ruleset: CompiledRuleset
): FilterEvaluationResult
// Returns: { matched: boolean, rule_id?, match_type?, pattern? }
// Priority: exact > contains > regex (short-circuits on first match)
Inherits standard CRUD: listFilterRules, createFilterRules, updateFilterRules, deleteFilterRules, listAndCountFilterRules, listAndCountBlockedMessageLogs, createBlockedMessageLogs.
Compiled Ruleset Structure
interface CompiledRuleset {
exactWords: Set<string> // Lowercase words for O(1) lookup
exactRules: Map<string, string> // word → rule_id
containsPatterns: Array<{ id: string; pattern: string }> // Lowercase
regexPatterns: Array<{ id: string; regex: RegExp }>
}
Compilation happens at module startup and is recompiled when rules change via admin CRUD workflows. Each workflow step (invalidateFilterCacheStep) recompiles the local in-memory cache and publishes to the Redis filter_rules_changed channel for future cross-instance support. Currently, filter recompilation is per-instance only — if running multiple instances, a restart or rule change on each instance is needed to refresh the cache.
Built-in Filter Rules
Seeded automatically on first startup:
| Rule | Type | Pattern | Purpose |
|---|---|---|---|
| Email addresses | Regex | [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,} |
Keep communication on-platform |
| Phone numbers | Regex | Various international formats | Prevent off-platform contact |
| URLs | Regex | https?://[^\s]+|www\.[^\s]+ |
Block spam and phishing |
Built-in rules cannot be deleted or have their pattern modified. Only is_enabled and description can be changed.
Messaging Redis Module
Identifier: messagingRedis
Provides Redis-backed infrastructure for real-time features. All methods degrade gracefully if Redis is unavailable.
Service: MessagingRedisModuleService
// Connection status
get isAvailable(): boolean
// SSE token management (one-time tokens with TTL)
setToken(token: string, value: string, ttlSeconds: number): Promise<void>
consumeToken(token: string): Promise<string | null> // Deletes after reading
// Sliding window rate limiting
checkRateLimit(
key: string, limit: number, windowSeconds: number
): Promise<{ allowed: boolean; count: number }>
// Pub/Sub
publish(channel: string, data: Record<string, unknown>): Promise<void>
createSubscriber(): Redis | null
// Notification throttle (SET NX EX)
trySetThrottle(key: string, ttlSeconds: number): Promise<boolean>
Redis Connection
// Connection options
{
lazyConnect: true,
maxRetriesPerRequest: 3,
retryStrategy: exponential backoff (max 5 retries, 2000ms cap)
}
If REDIS_URL is not provided or connection fails, the module registers a null connection and all Redis-dependent features are silently skipped.
Data Models
Conversation
| Field | Type | Constraints |
|---|---|---|
id |
string | Primary key, prefix: conv |
buyer_id |
string | Required |
seller_id |
string | Required |
last_message_preview |
string | null | Max 100 chars, auto-truncated |
last_message_sender_type |
"customer" | "seller" | null |
|
last_message_at |
datetime | null | Updated on each message |
unread_count_customer |
number | Default: 0 |
unread_count_seller |
number | Default: 0 |
created_at |
datetime | Auto |
updated_at |
datetime | Auto |
deleted_at |
datetime | null | Soft delete |
Indexes:
UNIQUE (buyer_id, seller_id)— one conversation per buyer-seller pair(seller_id, last_message_at, id)— vendor conversation listing(buyer_id, last_message_at, id)— buyer conversation listing
Relationship: messages — hasMany → Message
Message
| Field | Type | Constraints |
|---|---|---|
id |
string | Primary key, prefix: msg |
conversation_id |
string | Foreign key → Conversation |
sender_id |
string | Customer or seller ID |
sender_type |
"customer" | "seller" |
|
body |
string | 1–2000 characters |
context_type |
"product" | "order" | null |
|
context_id |
string | null | Product or order ID |
context_label |
string | null | Resolved label (product title or "Order #XYZ") |
read_at |
datetime | null | Set when recipient reads |
created_at |
datetime | Auto |
updated_at |
datetime | Auto |
deleted_at |
datetime | null | Soft delete |
Indexes:
(conversation_id, created_at, id)— message pagination within conversation(context_type, context_id)— context lookups(created_at)— global ordering
FilterRule
| Field | Type | Constraints |
|---|---|---|
id |
string | Primary key, prefix: filt |
match_type |
"exact" | "contains" | "regex" |
Custom rules: only exact or contains |
pattern |
string | 1–500 characters |
is_builtin |
boolean | Default: false. Built-in rules protected |
is_enabled |
boolean | Default: true |
description |
string | null | Max 500 characters |
created_at |
datetime | Auto |
updated_at |
datetime | Auto |
deleted_at |
datetime | null | Soft delete |
BlockedMessageLog
| Field | Type | Constraints |
|---|---|---|
id |
string | Primary key, prefix: bml |
sender_id |
string | Who sent the blocked message |
sender_type |
"customer" | "seller" |
|
conversation_id |
string | Where it was sent |
matched_rule_id |
string | Which rule blocked it |
message_body |
string | Full original message text |
created_at |
datetime | Auto |
updated_at |
datetime | Auto |
deleted_at |
datetime | null | Soft delete |
Retention: 30 days (cleaned up daily at 4 AM).
ChatBlock
| Field | Type | Constraints |
|---|---|---|
id |
string | Primary key, prefix: cblk |
customer_id |
string | Required |
blocked_by |
string | Admin user ID who blocked |
reason |
string | null | Optional reason for blocking |
created_at |
datetime | Auto |
updated_at |
datetime | Auto |
deleted_at |
datetime | null | Soft delete |
Indexes:
UNIQUE (customer_id)wheredeleted_at IS NULL— one active block per customer
A customer is either blocked or not — blocking is account-wide for chat (not per-conversation). The blocked_by field provides admin accountability. The unique index with a deleted_at IS NULL condition allows re-blocking after unblocking without conflicts.
Module Links
Conversation ↔ Customer
Links the customer module to conversation. One customer has many conversations. Enables query.graph() traversal from customer to their conversations.
Conversation ↔ Seller
Links the seller module to conversation. One seller has many conversations. Enables query.graph() traversal from seller to their conversations.
Workflows
sendMessageWorkflow
Creates a message in a conversation with full validation pipeline.
Input:
{
conversation_id: string
sender_id: string
sender_type: "customer" | "seller"
body: string // 1–2000 chars
context_type?: "product" | "order"
context_id?: string
context_label?: string // Pre-resolved by route
recipient_id: string
is_new_conversation: boolean
}
Steps:
- validateChatBlockStep — Checks if the customer (buyer) in this conversation is chat-blocked. Blocks both directions: blocked customers cannot send, and no one can send to a blocked customer.
- validateRateLimitStep — Checks 10 msg/60s and (if new conversation) 5 conv/3600s
- validateContentFilterStep — Evaluates against compiled ruleset, logs blocked
- createMessageStep — Atomic insert + conversation metadata update + unread increment
- publishMessageEventStep — Publishes
new_messageto Redis pub/sub - emitEventStep — Emits
messaging.message.createdMedusa event
Output: MessageDTO
Compensation: Step 3 deletes the message on rollback.
createConversationWorkflow
Creates a new buyer-seller conversation with module links.
Input: { buyer_id: string, seller_id: string }
Steps:
- createConversationStep — Creates conversation (unique constraint on buyer_id + seller_id)
- createRemoteLinkStep — Links conversation to customer and seller modules
Output: ConversationDTO
Compensation: Step 1 deletes the conversation on rollback.
markMessagesReadWorkflow
Marks all unread messages from the opposite party as read and publishes notification events.
Input:
{
conversation_id: string
reader_id: string
reader_type: "customer" | "seller"
sender_id: string // The opposite party
}
Steps:
- markMessagesReadStep — Atomic: sets
read_aton unread messages + resets reader's unread count - publishMessageEventStep (
messages_read) — Notifies sender their messages were read - publishMessageEventStep (
unread_count) — Confirms count reset to reader
Output: { conversation_id, updated: number }
anonymizeBuyerMessagesWorkflow
GDPR right-to-erasure handler for buyer deletion.
Input: { buyer_id: string }
Steps:
- Find all conversations where
buyer_idmatches (paginated, batch size: 100) - Update
buyer_idtodeleted_{buyer_id} - Set all message bodies to
"[Message removed]"(paginated, batch size: 100)
Compensation:
- Step 1 (find conversations): restores original
buyer_idon all matched conversations - Step 2 (anonymize messages): logs a warning — message body replacement is irreversible
anonymizeVendorMessagesWorkflow
Vendor offboarding handler.
Input: { seller_id: string }
Steps:
- Find all conversations where
seller_idmatches (paginated, batch size: 100) - Update
seller_idtodeleted_{seller_id} - Message bodies are preserved (vendor content remains per specification)
Compensation:
- Step 1 (find conversations): restores original
seller_idon all matched conversations
Filter Rule Workflows
| Workflow | Input | Behavior |
|---|---|---|
createFilterRuleWorkflow |
{ match_type, pattern, description?, is_enabled? } |
Creates rule, rejects regex type, invalidates cache |
updateFilterRuleWorkflow |
{ id, match_type?, pattern?, description?, is_enabled? } |
Updates rule, blocks pattern change on built-in rules |
deleteFilterRuleWorkflow |
{ id } |
Soft-deletes rule, blocks deletion of built-in rules |
All three recompile the local in-memory filter cache and publish filter_rules_changed to Redis (best-effort, for future cross-instance support).
blockCustomerWorkflow
Blocks a customer from chat. Idempotent — blocking an already-blocked customer returns the existing block record.
Input:
{
customer_id: string // Customer to block
blocked_by: string // Admin user ID performing the block
reason?: string | null // Optional reason
}
Steps:
- blockCustomerStep — Checks for existing block (idempotent). If none exists, creates a
ChatBlockrecord.
Output: ChatBlockDTO
Compensation: Deletes the created block record on rollback.
unblockCustomerWorkflow
Removes a chat block from a customer. Succeeds silently if the customer is not blocked.
Input:
{
customer_id: string // Customer to unblock
}
Steps:
- unblockCustomerStep — Finds and soft-deletes the existing
ChatBlockrecord.
Output: null
Compensation: Re-creates the deleted block record on rollback.
API Reference — Store (Customer)
All store endpoints require customer authentication via session or bearer token.
POST /store/messages — Create conversation
Creates a new conversation with a seller (or returns existing) and optionally sends the first message.
Request body:
{
seller_id: string // Required
body?: string // 1–2000 chars, optional
context_type?: "product" | "order" // Optional
context_id?: string // Required if context_type set
}
Validation: context_type and context_id must both be set or both omitted.
Response 200:
{
conversation: {
id: string
seller_id: string
last_message_preview: string | null
last_message_sender_type: "customer" | "seller" | null
last_message_at: string | null
unread_count_customer: number
created_at: string
}
message?: {
id: string
sender_type: "customer"
body: string
context_type: "product" | "order" | null
context_id: string | null
context_label: string | null
read_at: null
created_at: string
}
}
Behavior:
- Block check: If the customer is chat-blocked, returns
not_allowederror before any conversation/message processing - If conversation exists between buyer and seller, returns it (no duplicate)
- If
bodyprovided: validates block → validates rate limit → validates content filter → creates message - Resolves context labels: product title or "Order #display_id"
GET /store/messages — List conversations
Query parameters:
| Param | Type | Default | Range |
|---|---|---|---|
cursor |
string | — | Opaque cursor |
limit |
number | 20 | 1–50 |
Response 200:
{
conversations: Array<{
id: string
seller_id: string
last_message_preview: string | null
last_message_sender_type: "customer" | "seller" | null
last_message_at: string | null
unread_count_customer: number
created_at: string
}>
next_cursor: string | null
}
Ordered by last_message_at DESC, id DESC.
GET /store/messages/:id — Get messages
Query parameters:
| Param | Type | Default | Range |
|---|---|---|---|
cursor |
string | — | Opaque cursor |
limit |
number | 20 | 1–100 |
Response 200:
{
conversation: ConversationDTO
messages: Array<{
id: string
sender_type: "customer" | "seller"
body: string
context_type: "product" | "order" | null
context_id: string | null
context_label: string | null
read_at: string | null
created_at: string
}>
next_cursor: string | null
}
Messages returned in descending order (newest first). Reverse for chronological display.
Ownership check: conversation.buyer_id must match authenticated customer.
POST /store/messages/:id — Send message
Request body:
{
body: string // 1–2000 chars, required
context_type?: "product" | "order"
context_id?: string
}
Response 200:
{
message: {
id: string
sender_type: "customer"
body: string
context_type: "product" | "order" | null
context_id: string | null
context_label: string | null
read_at: null
created_at: string
}
}
Pipeline: ownership check → block check → rate limit → content filter → create message → publish SSE → emit event.
POST /store/messages/:id/read — Mark as read
Request body: {} (empty)
Response 200:
{
success: true
unread_count_customer: 0
}
Marks all unread seller messages as read. Publishes messages_read event to seller and unread_count event to customer.
GET /store/messages/unread — Unread count
Response 200:
{
unread_count: number
}
Total unread messages across all conversations for the authenticated customer.
POST /store/messages/sse-token — Get SSE token
Response 200:
{
token: string // UUID, one-time use
expires_in: 30 // seconds
}
Token stored in Redis: sse_token:{token} = customer_id with 30-second TTL. Consumed (deleted) on first SSE connection.
GET /store/messages/events?token={token} — SSE stream
Auth: Token-based (no session required). See SSE Real-Time Event System.
API Reference — Vendor (Seller)
All vendor endpoints require seller authentication.
GET /vendor/messages — List conversations
Query parameters: cursor?, limit? (1–50, default 20)
Response 200:
{
conversations: Array<ConversationDTO & {
buyer_first_name: string | null // Enriched
is_buyer_blocked: boolean // Chat block status
}>
next_cursor: string | null
}
GET /vendor/messages/:id — Get messages
Query parameters: cursor?, limit? (1–100, default 30)
Response 200:
{
conversation: ConversationDTO & {
buyer_first_name: string | null
is_buyer_blocked: boolean
}
messages: MessageDTO[]
next_cursor: string | null
buyer_orders: Array<{
id: string
display_id: number
status: string
total: number
currency_code: string
created_at: string
}>
}
The buyer_orders array contains the buyer's recent orders with this seller, enabling contextual customer support.
POST /vendor/messages/:id — Send reply
Request body:
{
body: string // 1–2000 chars, required
}
Vendor replies have no context linking (no context_type / context_id).
Block enforcement: If the buyer is chat-blocked, the vendor cannot send a reply. Returns not_allowed error: "Cannot send messages to a blocked customer".
Response 200: { message: MessageDTO }
POST /vendor/messages/:id/read — Mark as read
Response 200: { success: true, unread_count_seller: 0 }
GET /vendor/messages/unread — Unread count
Response 200: { unread_count: number }
GET /vendor/messages/events — SSE stream
Direct session-based auth (no token exchange). See SSE Real-Time Event System.
API Reference — Admin
All admin endpoints require admin user authentication. Admin has read-only access to conversations (cannot send messages) and can manage customer chat blocks.
GET /admin/messages — Search conversations
Query parameters:
| Param | Type | Description |
|---|---|---|
cursor |
string | Pagination cursor |
limit |
number (1–50, default 20) | Page size |
seller_name |
string | LIKE filter on seller name |
buyer_name |
string | LIKE filter on customer first or last name |
date_from |
string (ISO datetime) | Filter: last_message_at >= |
date_to |
string (ISO datetime) | Filter: last_message_at <= |
context_type |
"product" | "order" |
Filter by message context type |
context_id |
string | Filter by specific product/order ID |
Response 200:
{
conversations: Array<ConversationDTO & {
seller_name?: string
buyer_name?: string
buyer_email?: string
is_buyer_blocked: boolean
}>
next_cursor: string | null
}
GET /admin/messages/:id — Get messages
Response 200:
{
conversation: ConversationDTO & {
buyer_name: string | null
buyer_email: string | null
seller_name: string | null
is_buyer_blocked: boolean
block_reason: string | null // Present when is_buyer_blocked is true
}
messages: MessageDTO[] // includes sender_id
next_cursor: string | null
}
Admin can view any conversation without ownership restrictions. Admin message fields include sender_id (not exposed in store/vendor responses).
GET /admin/messages/filters — List filter rules
Query parameters: limit? (1–50, default 20)
Response 200:
{
filter_rules: Array<{
id: string
match_type: "exact" | "contains" | "regex"
pattern: string
is_builtin: boolean
is_enabled: boolean
description: string | null
created_at: string
updated_at: string
}>
count: number
}
POST /admin/messages/filters — Create filter rule
Request body:
{
match_type: "exact" | "contains" // "regex" not allowed for custom rules
pattern: string // 1–500 chars
description?: string // Max 500 chars
is_enabled?: boolean // Default: true
}
Response 200: { filter_rule: FilterRuleDTO }
Takes effect immediately (cache invalidated).
POST /admin/messages/filters/:id — Update filter rule
Request body:
{
match_type?: "exact" | "contains"
pattern?: string
description?: string
is_enabled?: boolean
}
Constraints:
- Built-in rules: only
is_enabledanddescriptioncan be changed - Attempting to modify a built-in rule's
patternormatch_typereturnsnot_allowed
Response 200: { filter_rule: FilterRuleDTO }
DELETE /admin/messages/filters/:id — Delete filter rule
Built-in rules cannot be deleted (returns not_allowed).
Response 200: { id: string, deleted: true }
GET /admin/messages/blocked — List blocked messages
Query parameters:
| Param | Type | Description |
|---|---|---|
cursor |
string | Pagination cursor |
limit |
number (1–50, default 20) | Page size |
sender_type |
"customer" | "seller" |
Filter by sender type |
date_from |
string | Filter: created_at >= |
date_to |
string | Filter: created_at <= |
Response 200:
{
blocked_messages: Array<{
id: string
sender_id: string
sender_type: "customer" | "seller"
conversation_id: string
matched_rule_id: string
message_body: string
created_at: string
}>
count: number
}
POST /admin/messages/chat-blocks — Block customer from chat
Request body:
{
customer_id: string // Required, customer to block
reason?: string // Optional, max 500 chars
}
Response 201:
{
block: {
id: string
customer_id: string
blocked_by: string // Admin user ID who performed the block
reason: string | null
created_at: string
updated_at: string
}
}
Behavior:
- Idempotent: blocking an already-blocked customer returns the existing block record
- The
blocked_byfield is set from the authenticated admin's ID - Takes effect immediately — blocked customer cannot create conversations or send messages
- Vendors cannot send messages to the blocked customer
GET /admin/messages/chat-blocks/:customer_id — Check block status
Response 200:
{
is_blocked: boolean
}
DELETE /admin/messages/chat-blocks/:customer_id — Unblock customer
Response 200:
{
success: true
}
Succeeds silently if the customer is not currently blocked.
GET /admin/messages/events — SSE stream
Direct session-based auth. Admin receives all messaging events globally (no filtering by recipient).
SSE Real-Time Event System
The plugin uses Server-Sent Events (SSE) over Redis pub/sub to deliver real-time updates to connected clients. All events are published to a single Redis channel (messaging) and filtered per-subscriber.
Connection Flows
| Actor | Endpoint | Auth Method | Filtering |
|---|---|---|---|
| Customer | GET /store/messages/events?token={token} |
One-time token (30s TTL) | Events where recipient_id or sender_id matches customer |
| Vendor | GET /vendor/messages/events |
Session/bearer | Events where recipient_id or sender_id matches seller |
| Admin | GET /admin/messages/events |
Session/bearer | No filtering — receives all events |
Store SSE Token Flow
EventSource cannot send custom headers, so store SSE uses a token exchange:
POST /store/messages/sse-token(authenticated) → returns{ token, expires_in: 30 }- Token stored in Redis:
sse_token:{token} = customer_id(30s TTL) GET /store/messages/events?token={token}(unauthenticated) — token consumed on connection- Token is one-time use — deleted from Redis after first consumption
Event Types
connected
Sent immediately on successful SSE connection.
event: connected
data: {"status":"connected"}
reconnected
Sent when client reconnects with Last-Event-ID header.
event: reconnected
data: {"status":"reconnected","last_event_id":"..."}
new_message
Published when a message is created in any conversation the subscriber is part of.
event: new_message
data: {
"conversation_id": "conv_01ABC",
"recipient_id": "cus_01XYZ",
"sender_type": "customer",
"event_type": "new_message",
"message_id": "msg_01DEF",
"context_type": "product",
"context_label": "Blue Widget"
}
messages_read
Published when the other party marks messages as read.
event: messages_read
data: {
"conversation_id": "conv_01ABC",
"event_type": "messages_read"
}
unread_count
Published when a user's unread count changes (after mark-read or new message).
event: unread_count
data: {
"conversation_id": "conv_01ABC",
"event_type": "unread_count",
"unread_count": 3
}
Heartbeat
A comment-only frame sent every 30 seconds to keep the connection alive:
:heartbeat
Reconnection
EventSourceauto-reconnects and sendsLast-Event-IDheader- Server sends
reconnectedevent but does not replay missed events - Clients should refetch conversations/messages after reconnection to catch up
- Store SSE: token is consumed, so reconnection requires a new token
- Dashboard SSE hooks use exponential backoff on error: 1s → 2s → 4s → 8s → ... → max 30s, reset to 1s on successful connection
Graceful Degradation
If Redis is unavailable, SSE connections cannot be established. Clients should fall back to polling the REST endpoints.
Cursor-Based Pagination
All list endpoints use cursor-based pagination for consistent performance regardless of dataset size.
How It Works
Cursors are opaque base64url-encoded JSON strings containing the sort fields of the last item in the current page. They encode { field_value, id } for deterministic ordering.
| Entity | Cursor Fields | Sort Order |
|---|---|---|
| Conversations | last_message_at, id |
DESC (most recent first) |
| Messages | created_at, id |
DESC (newest first) |
Pagination Limits
| Endpoint Type | Default | Max |
|---|---|---|
| Conversation lists | 20 | 50 |
| Message lists | 20 | 100 |
Usage Pattern
# First page
GET /store/messages?limit=20
→ { conversations: [...], next_cursor: "eyJ..." }
# Next page
GET /store/messages?limit=20&cursor=eyJ...
→ { conversations: [...], next_cursor: "eyJ..." }
# Last page
GET /store/messages?limit=20&cursor=eyJ...
→ { conversations: [...], next_cursor: null }
next_cursor is null when there are no more items. Cursors are opaque — never parse, modify, or construct them client-side.
Content Filtering
Every message (from both customers and sellers) passes through the content filter before being accepted.
Evaluation Pipeline
- Exact word match — Body split by whitespace, each word checked against
Set<string>(O(1) per word, case-insensitive) - Contains/substring match — Body checked against each pattern (lowercased, O(n) per pattern)
- Regex match — Body matched against compiled patterns (built-in rules only)
Evaluation short-circuits on first match. Priority: exact > contains > regex.
Rule Types
| Type | Available To | Matching |
|---|---|---|
exact |
Admin (custom) | Case-insensitive whole-word match |
contains |
Admin (custom) | Case-insensitive substring match |
regex |
Built-in only | Case-insensitive regex pattern |
When a Message Is Blocked
- Message is not created (rejected before insert)
- Full message body logged in
blocked_message_logwith matched rule ID - API returns
400with error typeinvalid_data - Blocked message logs retained for 30 days, cleaned up by scheduled job
Cache Management
- Rules compiled into memory at startup (via module loader)
- Lazily compiled on first message if startup compilation fails
- Recompiled on the current instance when any rule changes (create/update/delete) via
invalidateFilterCacheStep - The step also publishes to Redis
filter_rules_changedchannel for future cross-instance support - Note: Cross-instance invalidation requires a custom subscriber at the app level — not included by default due to MedusaJS module container limitations
- Functions:
getCompiledRuleset(),invalidateRuleset(),recompileFilters()
Rate Limiting
Enforced via Redis sliding window counters. Applies equally to customers and sellers.
| Limit | Threshold | Window | Redis Key |
|---|---|---|---|
| Messages per sender | 20 | 60 seconds | ratelimit:msg:{sender_id} |
| New conversations per sender | 5 | 3600 seconds (1 hour) | ratelimit:conv:{sender_id} |
Behavior
- Implemented in
validateRateLimitStepwithinsendMessageWorkflow - Uses
INCR+EXPIREfor atomic sliding window - Conversation rate limit only checked when
is_new_conversation: true - Exceeding limit throws
MedusaError.Types.NOT_ALLOWED - Graceful degradation: If Redis unavailable, rate limiting is skipped entirely
- Window is sliding (resets based on first message in window, not fixed clock)
Context Linking
Messages can be linked to a product or order, providing conversational context (e.g. "Question about this product", "Issue with order #1042").
Resolution
When a message includes context_type and context_id, the API route resolves a context_label before passing to the workflow:
| Context Type | Resolution | Label Format |
|---|---|---|
product |
Fetches product by ID | Product title (e.g. "Blue Cotton T-Shirt") |
order |
Fetches order by ID | "Order #<display_id>" (e.g. "Order #1042") |
Rules
context_typeandcontext_idmust both be provided or both omitted- Referenced product/order must exist (returns
404otherwise) - Label is resolved at send time and persisted — remains stable even if product title changes
- Different messages in the same conversation can reference different products/orders
- Vendor replies do not support context linking
Unread Tracking
Per-Conversation Counters
Each conversation tracks two independent unread counters:
unread_count_customer— messages from seller that the customer hasn't readunread_count_seller— messages from customer that the seller hasn't read
Counter Behavior
| Action | Customer Counter | Seller Counter |
|---|---|---|
| Customer sends message | No change | +1 |
| Seller sends message | +1 | No change |
| Customer marks read | → 0 | No change |
| Seller marks read | No change | → 0 |
Counters are updated atomically within the same database transaction as message creation or read marking.
Total Unread
GET /store/messages/unread and GET /vendor/messages/unread return the sum of unread counts across all conversations for the authenticated user.
Reconciliation
A scheduled job runs daily at 3 AM to reconcile drifted counters by counting actual unread messages and correcting any discrepancies.
GDPR & Data Privacy
Buyer Deletion
When a customer.deleted event fires:
anonymizeBuyerMessagesWorkflowruns automatically- All conversations:
buyer_id→deleted_{original_buyer_id}(paginated, 100 per batch) - All buyer messages:
body→"[Message removed]"(paginated, 100 per batch) - Module links to customer entity are cleaned up
- Compensation: conversation
buyer_idcan be restored; message body anonymization is irreversible (logged)
Vendor Deletion
When a seller.deleted event fires:
anonymizeVendorMessagesWorkflowruns automatically- All conversations:
seller_id→deleted_{original_seller_id}(paginated, 100 per batch) - Vendor message bodies are preserved (per business specification)
- Module links to seller entity are cleaned up
- Compensation: conversation
seller_idcan be restored
Data Retention
- Message data: retained indefinitely (soft delete only)
- Blocked message logs: 30-day retention, cleaned daily at 4 AM
- SSE tokens: 30-second TTL, auto-expired by Redis
- Rate limit counters: auto-expired by Redis (60s / 3600s TTL)
Chat Blocking
Admin-only feature to suspend a customer's chat access. Blocking prevents the customer from creating new conversations and sending messages, and prevents vendors from sending messages to the blocked customer. The customer's storefront account is unaffected.
How It Works
- Admin blocks customer via
POST /admin/messages/chat-blocks(with optional reason) - A
ChatBlockrecord is created with a unique index oncustomer_id - Block is enforced at three layers (defense in depth):
- Route level: Early exit before workflow execution (store and vendor POST handlers)
- Workflow step:
validateChatBlockStepruns first insendMessageWorkflow - UI level: Compose area disabled in vendor dashboard, admin dashboard shows badge
Block Enforcement Matrix
| Scenario | Result |
|---|---|
| Blocked customer creates conversation | not_allowed: "Your chat access has been suspended" |
| Blocked customer sends message | not_allowed: "Your chat access has been suspended" |
| Vendor sends to blocked customer | not_allowed: "Cannot send messages to a blocked customer" |
| Non-blocked customer sends message | Allowed (normal flow) |
| Admin blocks already-blocked customer | Idempotent — returns existing block |
| Admin unblocks non-blocked customer | Succeeds silently |
Bidirectional Blocking
When a customer is blocked, both directions are blocked:
- The customer cannot send messages to any vendor
- No vendor can send messages to the blocked customer
This prevents vendors from unknowingly engaging with a blocked user.
UI Indicators
| Dashboard | Location | Indicator |
|---|---|---|
| Admin list | Next to buyer name | Red "Blocked" badge |
| Admin detail | Sidebar + dedicated section | Red "Blocked" badge + Block/Unblock button |
| Vendor list | Next to buyer name | Red "Blocked" badge |
| Vendor detail | Sidebar + compose area | Red "Blocked" badge + disabled compose with notice |
Admin Block Dialog
The admin detail page provides:
- Block action: Opens an inline dialog with an optional reason input field and confirm/cancel buttons
- Unblock action: Shows a confirmation prompt via
usePromptbefore proceeding
Security
- Only admin users can create or remove blocks (no vendor or store routes for block management)
blocked_byfield records which admin performed the block- Block is enforced redundantly at route level, workflow level, and UI level
Event Subscribers
messaging.message.created
Handler: message-notification.ts
Triggered on every new message. Sends an email notification to the recipient.
Logic:
- Checks notification throttle: one email per conversation per recipient per 15 minutes (Redis key:
notify:{conversation_id}:{recipient_id}, TTL: 900s) - Resolves sender name (customer first name or seller name)
- Resolves recipient email address
- Sends notification via Medusa notification module
- Template:
messaging-new-message - Data:
{ sender_name, conversation_id } - Privacy: Message body is never included in emails
- Template:
customer.deleted
Handler: buyer-deletion.ts
Runs anonymizeBuyerMessagesWorkflow. See GDPR & Data Privacy.
seller.deleted
Handler: vendor-removal.ts
Runs anonymizeVendorMessagesWorkflow. See GDPR & Data Privacy.
Scheduled Jobs
Reconcile Unread Counts
Schedule: 0 3 * * * (daily at 3 AM)
Iterates through all conversations in batches of 500. For each conversation, counts actual unread messages for both parties. If the stored counter differs from the actual count, updates it. Logs all corrections.
Cleanup Blocked Messages
Schedule: 0 4 * * * (daily at 4 AM)
Soft-deletes blocked_message_log entries older than 30 days. Logs the number of records cleaned up.
Error Reference
| HTTP | Error Type | Cause | When |
|---|---|---|---|
| 400 | invalid_data |
Request validation failed | Missing/invalid fields, body too long/short |
| 400 | invalid_data |
Content filter matched | Message contains blocked content |
| 400 | not_allowed |
Rate limit exceeded | Too many messages or conversations in window |
| 400 | not_allowed |
Chat blocked (customer) | Blocked customer attempts to create conversation or send message |
| 400 | not_allowed |
Chat blocked (vendor) | Vendor attempts to send message to blocked customer |
| 400 | not_allowed |
Built-in rule modification | Attempting to delete or modify built-in filter pattern |
| 401 | unauthorized |
Missing/invalid authentication | No session, expired token |
| 401 | unauthorized |
SSE token invalid/expired/consumed | Token already used or past 30s TTL |
| 404 | not_found |
Conversation not found | Invalid ID or not owned by requester |
| 404 | not_found |
Referenced entity not found | Product or order ID doesn't exist |
All errors follow the standard Medusa error format:
{
"type": "not_allowed",
"message": "Rate limit exceeded. Please wait before sending more messages."
}
Testing
The plugin includes unit tests covering core logic:
cursor-encoding.spec.ts
- Base64url encoding roundtrip
- Conversation cursors (
last_message_at,id) - Message cursors (
created_at,id) - Null and numeric value handling
- Malformed input returns null
content-filter-eval.spec.ts
- Exact match: case-insensitive whole-word matching
- Contains: substring matching
- Regex: built-in patterns (email, phone, URL)
- Priority ordering: exact > contains > regex
- Short-circuit on first match
- Edge cases: empty message, whitespace, unicode
rate-limit.spec.ts
- 20 messages per 60 seconds enforced
- 5 conversations per 3600 seconds enforced
- Per-user isolation
- Applies equally to customers and sellers
- Window reset after expiry
unread-counter.spec.ts
- Only recipient counter increments
- Sender counter unchanged on own message
- Reset to 0 on mark read
- Accumulation across multiple messages
- Reconciliation corrects drifted counts
chat-block.spec.ts (unit)
- Block record creation with customer_id, blocked_by, reason
- Idempotent blocking (duplicate returns existing record)
- Unblocking removes block and allows chat again
- Unblocking non-blocked customer succeeds silently
- Re-blocking after unblock creates new record
- Batch checking (
checkBuyersBlocked) with mixed blocked/unblocked IDs - Bidirectional enforcement: blocked customer cannot send, vendor cannot send to blocked customer
- Multi-customer isolation: blocking one does not affect others
- Full lifecycle: block → verify → unblock → re-block cycle
- Admin accountability tracking (
blocked_byfield)
chat-block-api.spec.ts (integration)
- Admin block API: creates block record, returns 201 with block data
- Admin unblock API: removes block, returns success
- Idempotent block (returns existing on duplicate)
- Idempotent unblock (succeeds silently for non-blocked customer)
- Store enforcement: blocked customer cannot create conversations
- Store enforcement: blocked customer cannot send messages
- Vendor enforcement: vendor cannot reply to blocked customer
is_buyer_blockedandblock_reasonfields included in admin and vendor GET responses- Cross-feature interaction: block does not affect unrelated conversations
- Full lifecycle through API: block → enforce → unblock → verify restored access
Configuration Reference
Redis Keys
| Key Pattern | TTL | Purpose |
|---|---|---|
sse_token:{uuid} |
30s | One-time SSE auth token |
ratelimit:msg:{sender_id} |
60s | Message rate limit counter |
ratelimit:conv:{sender_id} |
3600s | Conversation creation rate limit counter |
notify:{conversation_id}:{recipient_id} |
900s | Email notification throttle |
Redis Pub/Sub Channels
| Channel | Publisher | Subscribers |
|---|---|---|
messaging |
publishMessageEventStep |
SSE route handlers (store, vendor, admin) |
filter_rules_changed |
invalidateFilterCacheStep |
None by default (available for custom cross-instance subscriber) |
Module Identifiers
| Module | Identifier | Container Key |
|---|---|---|
| Messaging | messaging |
messagingModuleService |
| Messaging Filters | messagingFilters |
messagingFiltersModuleService |
| Messaging Redis | messagingRedis |
messagingRedisModuleService |
Medusa Events Emitted
| Event | Payload | Trigger |
|---|---|---|
messaging.message.created |
{ id, conversation_id, sender_id, sender_type, recipient_id } |
After message creation |
Notification Templates
| Template ID | Variables | Usage |
|---|---|---|
messaging-new-message |
sender_name, conversation_id |
Email notification to message recipient |
Database Tables
| Table | Module | Prefix |
|---|---|---|
conversation |
messaging | conv |
message |
messaging | msg |
chat_block |
messaging | cblk |
filter_rule |
messagingFilters | filt |
blocked_message_log |
messagingFilters | bml |
Vendor Dashboard Pages
| Route | Description |
|---|---|
/messages |
Conversation list with unread badges |
/messages/:id |
Chat detail with reply composer and order sidebar |
Admin Dashboard Pages
| Route | Description |
|---|---|
/messages |
Searchable conversation list with seller/buyer names |
/messages/:id |
Read-only message thread with conversation metadata sidebar, block/unblock controls |
/messages/filters |
Content filter rule management |
/messages/blocked |
Blocked message log viewer |