@warriorteam/redai-zalo-sdk 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2025-01-08
+
+### Added
+
+#### 🆕 ConsultationService - Customer Support Messaging
+- **New Service**: `ConsultationService` for sending customer support messages within 48-hour interaction window
+- **Text Messages**: Send consultation text messages with automatic validation (max 2000 characters)
+- **Image Messages**: Send consultation images for visual support and guides
+- **File Messages**: Send consultation file attachments (manuals, guides, documents)
+- **Sticker Messages**: Send consultation sticker messages for friendly interactions
+- **General Messages**: Send any type of consultation message with unified interface
+
+#### 📚 Documentation & Examples
+- **Comprehensive Guide**: New `docs/CONSULTATION_SERVICE.md` with detailed usage instructions
+- **Practical Examples**: New `examples/consultation-service-example.ts` with 6 real-world scenarios
+- **Smart Customer Support**: Example implementation of intelligent customer support bot
+- **Webhook Integration**: Complete webhook integration examples for consultation service
+- **Error Handling**: Detailed error handling and retry mechanism examples
+
+#### 🔧 SDK Integration
+- **Quick Access**: Available via `zalo.consultation` property
+- **Quick Methods**: Added `zalo.sendConsultationText()` and `zalo.sendConsultationImage()` convenience methods
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **Error Handling**: Enhanced error handling with `ZaloSDKError` for consultation-specific errors
+
+#### 📖 Documentation Updates
+- **README.md**: Updated with ConsultationService examples and documentation links
+- **SERVICES_ADDED.md**: Added detailed ConsultationService documentation
+- **Keywords**: Enhanced package keywords for better discoverability
+
+### Technical Details
+
+#### Consultation Service Features
+- **48-Hour Window**: Enforces Zalo's 48-hour interaction window for consultation messages
+- **Content Validation**: Automatic validation of message content and format
+- **Quota Management**: Built-in quota tracking and management
+- **Anti-Spam**: Follows Zalo's anti-spam guidelines and best practices
+- **Retry Logic**: Built-in retry mechanism for failed requests
+
+#### Usage Conditions
+- Messages must be sent within 48 hours of last user interaction
+- Content must be consultation/support related (no direct advertising)
+- User must have followed the OA and not blocked it
+- No daily limit but must follow anti-spam guidelines
+
+#### Integration Points
+- Seamless integration with existing webhook system
+- Compatible with all existing SDK features
+- Follows established SDK patterns and conventions
+- Full backward compatibility maintained
+
+### Examples Added
+
+1. **Basic Consultation**: Simple text message consultation
+2. **Image Support**: Sending images for visual guidance
+3. **File Attachments**: Sending documents and manuals
+4. **Smart Customer Support**: AI-powered customer support bot
+5. **Retry Mechanism**: Robust error handling and retry logic
+6. **Webhook Integration**: Complete webhook event handling
+
+### Files Added/Modified
+
+#### New Files
+- `src/services/consultation.service.ts` - Main ConsultationService implementation
+- `docs/CONSULTATION_SERVICE.md` - Comprehensive documentation
+- `examples/consultation-service-example.ts` - Practical examples
+- `CHANGELOG.md` - This changelog file
+
+#### Modified Files
+- `README.md` - Added ConsultationService documentation and examples
+- `SERVICES_ADDED.md` - Added ConsultationService details
+- `package.json` - Updated version, description, keywords, and scripts
+- `src/index.ts` - Export ConsultationService types and classes
+- `src/zalo-sdk.ts` - Integrated ConsultationService into main SDK
+
+### Breaking Changes
+None. This release maintains full backward compatibility.
+
+### Migration Guide
+No migration required. All existing code will continue to work unchanged.
+
+To use the new ConsultationService:
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret"
+});
+
+// Use consultation service
+await zalo.consultation.sendTextMessage(
+  accessToken,
+  { user_id: "user-id" },
+  { type: "text", text: "How can I help you?" }
+);
+
+// Or use quick methods
+await zalo.sendConsultationText(accessToken, "user-id", "Hello!");
+```
+
+---
+
+## [1.1.1] - 2024-12-XX
+
+### Fixed
+- Bug fixes and stability improvements
+- Enhanced error handling
+- Documentation updates
+
+### Added
+- Additional webhook event types
+- Improved TypeScript definitions
+
+---
+
+## [1.1.0] - 2024-11-XX
+
+### Added
+- Group Management Service
+- Article Management Service
+- Video Upload Service
+- Enhanced webhook handling
+- Comprehensive documentation
+
+---
+
+## [1.0.0] - 2024-10-XX
+
+### Added
+- Initial release
+- Official Account API support
+- ZNS (Zalo Notification Service) support
+- Social API support
+- Authentication flow
+- Basic messaging capabilities
+- TypeScript support
+- Comprehensive error handling
+
+### Features
+- OAuth 2.0 authentication
+- Message sending (text, image, file, sticker)
+- User management
+- Template management
+- Quota monitoring
+- Webhook event handling

package/README.md

@@ -3,6 +3,7 @@
 A comprehensive TypeScript/JavaScript SDK for Zalo APIs, providing easy-to-use interfaces for:
 
 - **Official Account (OA) API** - Manage your Zalo Official Account
+- **Consultation Service** - Send customer support messages within 48-hour window
 - **Zalo Notification Service (ZNS)** - Send template-based notification messages
 - **Social API** - Access user social information and authentication
 - **Group Message Framework (GMF)** - Send messages to Zalo groups
@@ -35,6 +36,7 @@ npm install @warriorteam/redai-zalo-sdk
 - **[Services Added](./SERVICES_ADDED.md)** - Detailed breakdown of all services and features
 - **[Group Management](./docs/GROUP_MANAGEMENT.md)** - Group messaging and management
 - **[Article Management](./docs/ARTICLE_MANAGEMENT.md)** - Content and article management
+- **[Consultation Service](./docs/CONSULTATION_SERVICE.md)** - Customer service messaging guide
 
 ## Development
 
@@ -319,6 +321,49 @@ For support and questions:
 - Create an issue on GitHub
 - Contact RedAI team
 
+### Consultation Service (Customer Support)
+
+```typescript
+// Send consultation text message
+await zalo.consultation.sendTextMessage(accessToken,
+  { user_id: "user-id" },
+  {
+    type: "text",
+    text: "Xin chào! Tôi có thể hỗ trợ gì cho bạn?"
+  }
+);
+
+// Send consultation image with guide
+await zalo.consultation.sendImageMessage(accessToken,
+  { user_id: "user-id" },
+  {
+    type: "image",
+    attachment: {
+      type: "image",
+      payload: {
+        url: "https://example.com/support-guide.jpg"
+      }
+    }
+  }
+);
+
+// Send file attachment for support
+await zalo.consultation.sendFileMessage(accessToken,
+  { user_id: "user-id" },
+  {
+    type: "file",
+    url: "https://example.com/manual.pdf",
+    filename: "User Manual.pdf",
+    attachment: {
+      type: "file",
+      payload: {
+        url: "https://example.com/manual.pdf"
+      }
+    }
+  }
+);
+```
+
 ### ZNS (Zalo Notification Service)
 
 ```typescript

package/SERVICES_ADDED.md

@@ -4,7 +4,44 @@ This document summarizes all the services that have been added to the RedAI Zalo
 
 ## New Services Added
 
-### 1. ZNSService (`src/services/zns.service.ts`)
+### 1. ConsultationService (`src/services/consultation.service.ts`)
+
+**Purpose**: Customer Service messaging for sending consultation messages within 48-hour window
+
+**Key Features**:
+
+- Send consultation text messages
+- Send consultation image messages
+- Send consultation file messages
+- Send consultation sticker messages
+- Send general consultation messages
+- Automatic validation of message content
+- Built-in error handling and retry logic
+- 48-hour interaction window enforcement
+
+**Main Methods**:
+
+- `sendTextMessage()` - Send consultation text message (max 2000 characters)
+- `sendImageMessage()` - Send consultation image with support content
+- `sendFileMessage()` - Send consultation file attachments (guides, manuals)
+- `sendStickerMessage()` - Send consultation sticker messages
+- `sendMessage()` - Send any type of consultation message
+
+**Usage Conditions**:
+
+- Must be sent within 48 hours of last user interaction
+- Content must be consultation/support related (no direct advertising)
+- User must have followed the OA and not blocked it
+- No daily limit but must follow anti-spam guidelines
+
+**Integration**:
+
+- Accessible via `zalo.consultation` property
+- Quick methods: `zalo.sendConsultationText()`, `zalo.sendConsultationImage()`
+- Full webhook integration support
+- Comprehensive error handling with ZaloSDKError
+
+### 2. ZNSService (`src/services/zns.service.ts`)
 
 **Purpose**: Zalo Notification Service for sending template-based notifications