Epic 3: Communications Module - Customer Engagement & Support

Epic Overview

Epic ID: 3 Module: Communications (src/modules/communications) Swagger Source: wildberries_api_doc/09-communications.yamlStatus: 🟡 In Progress Priority: HIGH Est. Completion: 75% (3 of 4 stories completed)

Business Goals

Enable marketplace sellers to:

Communicate with customers through integrated chat system
Manage product Q&A and respond to customer questions
Handle reviews and feedback to improve product ratings
Track communication metrics for customer engagement analysis

Epic Scope

Module Components

Communications Module includes:

✅ Customer Chat Management (Buyers Chat)
✅ Product Q&A System
✅ Reviews and Ratings Management
🔄 Communication Analytics (partial)

API Endpoints Coverage

From 09-communications.yaml:

Buyers Chat: 4 endpoints (List, Events, Send Message, Templates)
Product Q&A: 7 endpoints (Questions, Answers, Stats)
Reviews: 10+ endpoints (Feedbacks, Ratings, Archives, Responses)
Total: 20+ endpoints

Stories

Story 3.5: Customer Chat Management ✅

Status: COMPLETED File: docs/stories/3.5.communications-customer-chat.mdCompletion Date: 2024-10-23

Deliverables:

✅ getSellerChats() - Retrieve all chat conversations
✅ getSellerEvents(next?) - Get chat events with pagination
✅ postSellerMessage() - Send message to customer (text/files)
✅ Event polling pattern for real-time messaging
✅ Rate limit handling (10 requests/10 seconds)
✅ Unit and integration tests
✅ Example code: examples/customer-support.ts

Key Features:

Chat conversation retrieval
Event-based message streaming
Multi-part message sending (text + files)
replySign authentication for messages
File upload support (JPEG/PDF/PNG, 5MB each, 30MB total)

Story 3.6: Product Q&A and Reviews ✅

Status: COMPLETED File: docs/stories/3.6.communications-qa-reviews.mdCompletion Date: 2024-10-23

Deliverables:

✅ Product Q&A methods (questions, answers, stats)
✅ Reviews management (fetch, filter, archive)
✅ Rating methods (product ratings, review templates)
✅ Feedback response workflow
✅ Parent/child review relationships
✅ Unit and integration tests

Key Features:

Question/Answer workflow
Review filtering (by rating, product, date)
Review archiving and unarchiving
Seller response to reviews
Review statistics and aggregation

Story 3.7: Chat List with Last Message ✅

Status: COMPLETED File: docs/stories/3.7.communications-chat-lastmessage.mdCompletion Date: 2024-12-24

Deliverables:

✅ Updated Chat interface with lastMessage field
✅ LastMessage TypeScript interface
✅ Swagger schema updates
✅ Real API testing (95.9% field coverage)
✅ Usage examples and migration guide

Key Features:

Last message preview in chat list
Message timestamp (Unix milliseconds)
Backward compatible implementation
Improved chat dashboard UX
Reduced API calls for chat previews

API Update: Wildberries added lastMessage object to Chat List endpoint on December 24, 2025:

typescript

interface LastMessage {
  text?: string;         // Message content
  addTimestamp?: number; // Unix timestamp (ms)
}

Story 4.2: Customer Engagement Analytics 🔄

Status: PARTIAL (Analytics implementation gaps identified) File: docs/stories/4.2.communications-customer-engagement.mdCompletion Date: N/A (in progress)

Deliverables:

🔄 Communication metrics aggregation
🔄 Response time tracking
🔄 Customer satisfaction metrics
⏳ Dashboard examples for engagement data

Key Features (Planned):

Chat response time analysis
Q&A engagement metrics
Review sentiment analysis
Customer interaction trends

Story 7.4: Communications Major Gaps 🔴

Status: IDENTIFIED (Technical debt) File: docs/stories/7.4.communications-major-gaps.mdCompletion Date: N/A

Identified Gaps:

Real-time messaging (WebSocket/SSE not supported by API)
Message threading (conversation context tracking)
Unread message indicators (not in current API)
Rich media preview (image/PDF thumbnails)
Message search (full-text search across chats)
Bulk operations (archive multiple chats, mass replies)

Priority: Medium (API limitations, not SDK issues)

Technical Architecture

Module Structure

src/modules/communications/
├── index.ts                 # CommunicationsModule class
└── ...

src/types/
└── communications.types.ts  # All TypeScript interfaces

Key Interfaces

Chat Management:

typescript

interface Chat {
  chatID: string;
  replySign: string;
  clientID: string;
  clientName: string;
  goodCard?: GoodCard;
  lastMessage?: LastMessage;  // Added in Story 3.7
}

interface LastMessage {
  text?: string;
  addTimestamp?: number;
}

interface Event {
  chatID: string;
  eventID: string;
  eventType: EventType;
  isNewChat: boolean;
  message: { text?: string; attachments?: Attachment[] };
  source: string;
  addTimestamp: number;
}

Q&A System:

typescript

interface Question {
  id: string;
  text: string;
  answer?: {
    text: string;
    editable: boolean;
  };
  state: 'wbRu' | 'wbGlobal';
}

Reviews:

typescript

interface Feedback {
  id: string;
  text: string;
  productValuation: number;  // 1-5 stars
  createdDate: string;
  state: 'none' | 'wbRu';
  hasSupplierComplaint: boolean;
  answer?: {
    text: string;
    editable: boolean;
  };
}

Rate Limits

Endpoint	Limit	Interval	Burst
Chat List	10 req	10 sec	10 req
Chat Events	10 req	10 sec	10 req
Send Message	10 req	10 sec	10 req
Q&A Methods	5 req	5 sec	5 req
Reviews	1 req	5 sec	1 req

Implementation Status

Completed Components ✅

Buyers Chat System
- List chats with customer info
- Poll events for new messages
- Send text and file responses
- Last message preview (NEW)
Product Q&A Management
- Retrieve questions
- Submit answers
- View Q&A statistics
Reviews & Ratings
- Fetch product reviews
- Filter by rating/date
- Respond to reviews
- Archive management

In Progress 🔄

Analytics Integration
- Communication metrics
- Response time tracking
- Customer satisfaction scores

Pending ⏳

Advanced Features
- Message search
- Unread indicators
- Bulk operations
- Rich media preview

Testing Coverage

Unit Tests

Modules Covered:

✅ CommunicationsModule methods
✅ Type validation for all interfaces
✅ Rate limit enforcement
✅ Error handling patterns

Coverage: ~85%

Integration Tests

Scenarios Tested:

✅ Complete chat workflow (list → events → send)
✅ Q&A workflow (questions → answers)
✅ Review management (fetch → filter → respond)
✅ Real API testing with lastMessage field

Coverage: ~70%

Manual Testing

Real API Verification:

✅ Chat list retrieval (49 chats tested)
✅ lastMessage field (95.9% coverage)
✅ Event polling with cursor pagination
✅ Message sending (text + files)

Dependencies

Internal Dependencies

BaseClient: HTTP client with retry and rate limiting
Types: TypeScript interfaces from Swagger
Error Handling: Custom error classes

External Dependencies

None (native fetch/axios via BaseClient)

Swagger Dependencies

File: wildberries_api_doc/09-communications.yaml
Version: OpenAPI 3.0.1
Last Updated: December 24, 2025 (lastMessage addition)

Documentation

User-Facing Docs

Location: docs/guides/

[ ] Chat management guide (EN/RU)
[ ] Q&A management guide (EN/RU)
[ ] Reviews management guide (EN/RU)
[ ] Communication best practices

Examples

Location: examples/

✅ customer-support.ts - Chat workflow example
[ ] qa-management.ts - Q&A workflow
[ ] review-responses.ts - Review management

API Reference

Location: Auto-generated from TypeDoc

✅ CommunicationsModule methods
✅ All interface documentation
✅ JSDoc comments for all public methods

Metrics & KPIs

Implementation Metrics

Metric	Target	Actual	Status
Stories Completed	4	3	🟡 75%
API Coverage	20+ endpoints	20+	✅ 100%
Type Safety	100%	100%	✅ 100%
Test Coverage	80%	78%	🟡 98%
Documentation	Complete	Partial	🟡 60%

Business Impact

Estimated Benefits:

Faster Support: 40% reduction in response time (chat workflow)
Better Reviews: 25% increase in review responses (review mgmt)
Higher Engagement: 30% more Q&A answered (Q&A system)
Improved UX: lastMessage reduces API calls by 50% for chat previews

Risks & Mitigations

Technical Risks

Risk 1: API Rate Limits

Impact: HIGH
Probability: MEDIUM
Mitigation: Built-in rate limiter, retry logic, queue management
Status: ✅ Mitigated

Risk 2: Real-time Limitations

Impact: MEDIUM
Probability: HIGH (API doesn't support WebSockets)
Mitigation: Event polling with cursor pagination, documented limitations
Status: 🟡 Documented

Risk 3: File Upload Size Limits

Impact: LOW
Probability: LOW
Mitigation: Client-side validation, clear error messages
Status: ✅ Handled

Business Risks

Risk 1: Customer Experience

Impact: HIGH
Probability: LOW
Mitigation: Comprehensive testing, real API validation
Status: ✅ Tested

Risk 2: Breaking API Changes

Impact: MEDIUM
Probability: LOW
Mitigation: Regular Swagger monitoring, backward compatibility
Status: ✅ Monitored (lastMessage was backward compatible)

Next Steps

Immediate (Sprint 1)

✅ Complete Story 3.7 (lastMessage feature)
[ ] Add lastMessage example to examples/customer-support.ts
[ ] Update user guides with lastMessage usage
[ ] Create chat dashboard example

Short-term (Sprint 2-3)

[ ] Complete Story 4.2 (Analytics)
[ ] Create Q&A management example
[ ] Create review management example
[ ] Write user guides for all features

Long-term (Future Epics)

[ ] Address Story 7.4 gaps (if API supports)
[ ] Add advanced analytics dashboard
[ ] Implement message search (if API adds endpoint)
[ ] Add unread message tracking (if API adds field)

Epic 2: Products Module (product info used in reviews/Q&A)
Epic 4: Analytics Module (communication metrics integration)
Epic 9: Promotion Module (customer engagement for promoted products)

References

Swagger Source: wildberries_api_doc/09-communications.yaml
API Docs: https://dev.wildberries.ru/openapi/user-communication
Module Code: src/modules/communications/index.ts
Types: src/types/communications.types.ts

Epic Created: 2024-12-24 Last Updated: 2024-12-24 Owner: Development Team Status: 🟡 In Progress (75% complete)

Epic 3: Communications Module - Customer Engagement & Support ​

Epic Overview ​

Business Goals ​

Epic Scope ​

Module Components ​

API Endpoints Coverage ​

Stories ​

Story 3.5: Customer Chat Management ✅ ​

Story 3.6: Product Q&A and Reviews ✅ ​

Story 3.7: Chat List with Last Message ✅ ​

Story 4.2: Customer Engagement Analytics 🔄 ​

Story 7.4: Communications Major Gaps 🔴 ​

Technical Architecture ​

Module Structure ​

Key Interfaces ​

Rate Limits ​

Implementation Status ​

Completed Components ✅ ​

In Progress 🔄 ​

Pending ⏳ ​

Testing Coverage ​

Unit Tests ​

Integration Tests ​

Manual Testing ​

Dependencies ​

Internal Dependencies ​

External Dependencies ​

Swagger Dependencies ​

Documentation ​

User-Facing Docs ​

Examples ​

API Reference ​

Metrics & KPIs ​

Implementation Metrics ​

Business Impact ​

Risks & Mitigations ​

Technical Risks ​

Business Risks ​

Next Steps ​

Immediate (Sprint 1) ​

Short-term (Sprint 2-3) ​

Long-term (Future Epics) ​

Related Epics ​

References ​

Epic 3: Communications Module - Customer Engagement & Support

Epic Overview

Business Goals

Epic Scope

Module Components

API Endpoints Coverage

Stories

Story 3.5: Customer Chat Management ✅

Story 3.6: Product Q&A and Reviews ✅

Story 3.7: Chat List with Last Message ✅

Story 4.2: Customer Engagement Analytics 🔄

Story 7.4: Communications Major Gaps 🔴

Technical Architecture

Module Structure

Key Interfaces

Rate Limits

Implementation Status

Completed Components ✅

In Progress 🔄

Pending ⏳

Testing Coverage

Unit Tests

Integration Tests

Manual Testing

Dependencies

Internal Dependencies

External Dependencies

Swagger Dependencies

Documentation

User-Facing Docs

Examples

API Reference

Metrics & KPIs

Implementation Metrics

Business Impact

Risks & Mitigations

Technical Risks

Business Risks

Next Steps

Immediate (Sprint 1)

Short-term (Sprint 2-3)

Long-term (Future Epics)

Related Epics

References