@warriorteam/redai-zalo-sdk 1.1.1 → 1.2.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
 

package/docs/CONSULTATION_SERVICE.md

@@ -0,0 +1,330 @@
+# Consultation Service - Hướng Dẫn Sử Dụng
+
+## Tổng Quan
+
+`ConsultationService` là dịch vụ chuyên dụng để gửi tin nhắn tư vấn (Customer Service) qua Zalo Official Account. Tin nhắn tư vấn cho phép OA gửi tin nhắn chủ động đến người dùng trong khung thời gian nhất định để hỗ trợ và tư vấn khách hàng.
+
+## Điều Kiện Gửi Tin Nhắn Tư Vấn
+
+### 1. Thời Gian Gửi
+- **Khung thời gian**: Chỉ được gửi trong vòng **48 giờ** kể từ khi người dùng tương tác cuối cùng với OA
+- **Tương tác bao gồm**:
+  - Gửi tin nhắn đến OA
+  - Nhấn button/quick reply
+  - Gọi điện thoại từ OA
+  - Truy cập website từ OA
+
+### 2. Nội Dung Tin Nhắn
+- **Mục đích**: Phải liên quan đến tư vấn, hỗ trợ khách hàng
+- **Bao gồm**: Trả lời câu hỏi, hướng dẫn sử dụng, hỗ trợ kỹ thuật
+- **Không được**: Chứa nội dung quảng cáo trực tiếp
+
+### 3. Điều Kiện Người Dùng
+- Người dùng phải đã follow OA
+- Người dùng không được block OA
+- Người dùng phải có tương tác gần đây với OA
+
+### 4. Tần Suất Gửi
+- Không giới hạn số lượng tin nhắn tư vấn trong ngày
+- Cần tuân thủ nguyên tắc không spam
+
+## Khởi Tạo Service
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+  debug: true
+});
+
+// Lấy consultation service
+const consultationService = zalo.consultation;
+```
+
+## Các Phương Thức Chính
+
+### 1. Gửi Tin Nhắn Văn Bản
+
+```typescript
+// Gửi tin nhắn văn bản tư vấn
+const response = await consultationService.sendTextMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "text",
+    text: "Xin chào! Tôi có thể hỗ trợ gì cho bạn?"
+  }
+);
+
+console.log("Message ID:", response.message_id);
+console.log("Quota remaining:", response.quota?.remain);
+```
+
+**Giới hạn văn bản:**
+- Nội dung không được để trống
+- Tối đa 2000 ký tự
+
+### 2. Gửi Tin Nhắn Hình Ảnh
+
+```typescript
+// Gửi hình ảnh tư vấn
+const response = await consultationService.sendImageMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "image",
+    attachment: {
+      type: "image",
+      payload: {
+        url: "https://example.com/support-image.jpg"
+      }
+    }
+  }
+);
+```
+
+### 3. Gửi File Đính Kèm
+
+```typescript
+// Gửi file hướng dẫn
+const response = await consultationService.sendFileMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "file",
+    url: "https://example.com/user-manual.pdf",
+    filename: "Hướng dẫn sử dụng.pdf",
+    attachment: {
+      type: "file",
+      payload: {
+        url: "https://example.com/user-manual.pdf"
+      }
+    }
+  }
+);
+```
+
+### 4. Gửi Sticker
+
+```typescript
+// Gửi sticker thân thiện
+const response = await consultationService.sendStickerMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "sticker",
+    sticker_id: "sticker-id",
+    attachment: {
+      type: "sticker",
+      payload: {
+        id: "sticker-id"
+      }
+    }
+  }
+);
+```
+
+### 5. Gửi Tin Nhắn Tổng Quát
+
+```typescript
+// Gửi bất kỳ loại tin nhắn nào
+const response = await consultationService.sendMessage(
+  accessToken,
+  { user_id: "user-id-here" },
+  {
+    type: "text",
+    text: "Cảm ơn bạn đã liên hệ. Chúng tôi sẽ hỗ trợ bạn ngay!"
+  }
+);
+```
+
+## Xử Lý Lỗi
+
+```typescript
+import { ZaloSDKError } from "@warriorteam/redai-zalo-sdk";
+
+try {
+  const response = await consultationService.sendTextMessage(
+    accessToken,
+    { user_id: "user-id" },
+    { type: "text", text: "Hello!" }
+  );
+} catch (error) {
+  if (error instanceof ZaloSDKError) {
+    console.error("Zalo API Error:", error.message);
+    console.error("Error Code:", error.code);
+    
+    // Xử lý các lỗi phổ biến
+    switch (error.code) {
+      case -216:
+        console.log("Access token không hợp lệ");
+        break;
+      case -201:
+        console.log("Tham số không hợp lệ");
+        break;
+      case -223:
+        console.log("Đã vượt quá quota");
+        break;
+      default:
+        console.log("Lỗi khác:", error.message);
+    }
+  }
+}
+```
+
+## Ví Dụ Thực Tế
+
+### Hệ Thống Hỗ Trợ Khách Hàng
+
+```typescript
+class CustomerSupportBot {
+  constructor(private consultationService: ConsultationService) {}
+
+  async handleUserQuestion(accessToken: string, userId: string, question: string) {
+    try {
+      // Phân tích câu hỏi và tạo phản hồi
+      const response = this.generateResponse(question);
+      
+      // Gửi tin nhắn tư vấn
+      await this.consultationService.sendTextMessage(
+        accessToken,
+        { user_id: userId },
+        {
+          type: "text",
+          text: response
+        }
+      );
+
+      // Gửi thêm hình ảnh hướng dẫn nếu cần
+      if (this.needsVisualGuide(question)) {
+        await this.consultationService.sendImageMessage(
+          accessToken,
+          { user_id: userId },
+          {
+            type: "image",
+            attachment: {
+              type: "image",
+              payload: {
+                url: "https://example.com/guide-image.jpg"
+              }
+            }
+          }
+        );
+      }
+
+    } catch (error) {
+      console.error("Failed to send consultation message:", error);
+    }
+  }
+
+  private generateResponse(question: string): string {
+    // Logic tạo phản hồi dựa trên câu hỏi
+    if (question.includes("đăng nhập")) {
+      return "Để đăng nhập, bạn vui lòng làm theo các bước sau...";
+    }
+    
+    if (question.includes("thanh toán")) {
+      return "Về vấn đề thanh toán, chúng tôi hỗ trợ các phương thức...";
+    }
+    
+    return "Cảm ơn bạn đã liên hệ. Chúng tôi sẽ hỗ trợ bạn ngay!";
+  }
+
+  private needsVisualGuide(question: string): boolean {
+    return question.includes("hướng dẫn") || question.includes("cách làm");
+  }
+}
+```
+
+### Tích Hợp Với Webhook
+
+```typescript
+// Xử lý tin nhắn từ webhook
+app.post('/webhook', async (req, res) => {
+  const event = req.body;
+  
+  if (event.event_name === 'user_send_text') {
+    const userId = event.sender.id;
+    const userMessage = event.message.text;
+    
+    // Kiểm tra xem có phải câu hỏi cần hỗ trợ không
+    if (userMessage.includes('help') || userMessage.includes('hỗ trợ')) {
+      
+      // Gửi tin nhắn tư vấn
+      await consultationService.sendTextMessage(
+        accessToken,
+        { user_id: userId },
+        {
+          type: "text",
+          text: "Tôi có thể hỗ trợ bạn về các vấn đề sau:\n1. Đăng nhập\n2. Thanh toán\n3. Sử dụng sản phẩm\nBạn cần hỗ trợ về vấn đề nào?"
+        }
+      );
+    }
+  }
+  
+  res.status(200).send('OK');
+});
+```
+
+## Best Practices
+
+### 1. Kiểm Tra Thời Gian Tương Tác
+```typescript
+// Kiểm tra thời gian tương tác cuối cùng trước khi gửi
+const lastInteraction = await getUserLastInteraction(userId);
+const hoursSinceLastInteraction = (Date.now() - lastInteraction) / (1000 * 60 * 60);
+
+if (hoursSinceLastInteraction > 48) {
+  console.log("Không thể gửi tin nhắn tư vấn - quá 48 giờ");
+  return;
+}
+```
+
+### 2. Quản Lý Quota
+```typescript
+// Kiểm tra quota trước khi gửi
+const quota = await zalo.oa.getQuotaSummary(accessToken);
+if (quota.consultation.remaining <= 0) {
+  console.log("Đã hết quota tin nhắn tư vấn");
+  return;
+}
+```
+
+### 3. Retry Logic
+```typescript
+async function sendWithRetry(
+  consultationService: ConsultationService,
+  accessToken: string,
+  recipient: MessageRecipient,
+  message: Message,
+  maxRetries = 3
+) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await consultationService.sendMessage(accessToken, recipient, message);
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      
+      // Đợi trước khi retry
+      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+    }
+  }
+}
+```
+
+## Lưu Ý Quan Trọng
+
+1. **Tuân thủ chính sách**: Chỉ gửi tin nhắn tư vấn thực sự, không spam
+2. **Theo dõi quota**: Kiểm tra quota thường xuyên để tránh vượt giới hạn
+3. **Xử lý lỗi**: Luôn có cơ chế xử lý lỗi phù hợp
+4. **Logging**: Ghi log để theo dõi và debug
+5. **Rate limiting**: Tránh gửi quá nhiều tin nhắn trong thời gian ngắn
+
+## Tài Liệu Liên Quan
+
+- [Message Types](./MESSAGE_TYPES.md) - Các loại tin nhắn được hỗ trợ
+- [Webhook Events](./WEBHOOK_EVENTS.md) - Xử lý sự kiện webhook
+- [Error Handling](./ERROR_HANDLING.md) - Xử lý lỗi chi tiết
+- [Quota Management](./QUOTA_MANAGEMENT.md) - Quản lý quota tin nhắn

package/examples/consultation-service-example.ts

@@ -0,0 +1,390 @@
+/**
+ * Ví dụ sử dụng ConsultationService - Dịch vụ tin nhắn tư vấn
+ * 
+ * Ví dụ này minh họa cách sử dụng ConsultationService để:
+ * - Gửi tin nhắn tư vấn văn bản
+ * - Gửi hình ảnh hỗ trợ
+ * - Gửi file hướng dẫn
+ * - Xử lý lỗi và retry
+ * - Tích hợp với webhook
+ */
+
+import { ZaloSDK, ZaloSDKError, SendMessageResponse } from "../src/index";
+
+// Cấu hình SDK
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret",
+  debug: true
+});
+
+// Access token của OA (lấy từ quá trình authentication)
+const ACCESS_TOKEN = "your-oa-access-token";
+
+/**
+ * Ví dụ 1: Gửi tin nhắn tư vấn cơ bản
+ */
+async function basicConsultationExample() {
+  console.log("=== Ví dụ 1: Tin nhắn tư vấn cơ bản ===");
+  
+  try {
+    // Gửi tin nhắn văn bản tư vấn
+    const response = await zalo.consultation.sendTextMessage(
+      ACCESS_TOKEN,
+      { user_id: "user-id-here" },
+      {
+        type: "text",
+        text: "Xin chào! Cảm ơn bạn đã liên hệ với chúng tôi. Tôi có thể hỗ trợ gì cho bạn hôm nay?"
+      }
+    );
+
+    console.log("✅ Gửi tin nhắn thành công!");
+    console.log("Message ID:", response.message_id);
+    console.log("User ID:", response.user_id);
+    
+    if (response.quota) {
+      console.log("Quota còn lại:", response.quota.remain);
+    }
+
+  } catch (error) {
+    if (error instanceof ZaloSDKError) {
+      console.error("❌ Lỗi Zalo API:", error.message);
+      console.error("Mã lỗi:", error.code);
+    } else {
+      console.error("❌ Lỗi không xác định:", error);
+    }
+  }
+}
+
+/**
+ * Ví dụ 2: Gửi hình ảnh hỗ trợ
+ */
+async function imageConsultationExample() {
+  console.log("\n=== Ví dụ 2: Gửi hình ảnh hỗ trợ ===");
+  
+  try {
+    const response = await zalo.consultation.sendImageMessage(
+      ACCESS_TOKEN,
+      { user_id: "user-id-here" },
+      {
+        type: "image",
+        attachment: {
+          type: "image",
+          payload: {
+            url: "https://example.com/support-guide.jpg"
+          }
+        }
+      }
+    );
+
+    console.log("✅ Gửi hình ảnh hỗ trợ thành công!");
+    console.log("Message ID:", response.message_id);
+
+  } catch (error) {
+    console.error("❌ Lỗi gửi hình ảnh:", error);
+  }
+}
+
+/**
+ * Ví dụ 3: Gửi file hướng dẫn
+ */
+async function fileConsultationExample() {
+  console.log("\n=== Ví dụ 3: Gửi file hướng dẫn ===");
+  
+  try {
+    const response = await zalo.consultation.sendFileMessage(
+      ACCESS_TOKEN,
+      { user_id: "user-id-here" },
+      {
+        type: "file",
+        url: "https://example.com/user-manual.pdf",
+        filename: "Hướng dẫn sử dụng.pdf",
+        attachment: {
+          type: "file",
+          payload: {
+            url: "https://example.com/user-manual.pdf"
+          }
+        }
+      }
+    );
+
+    console.log("✅ Gửi file hướng dẫn thành công!");
+    console.log("Message ID:", response.message_id);
+
+  } catch (error) {
+    console.error("❌ Lỗi gửi file:", error);
+  }
+}
+
+/**
+ * Ví dụ 4: Hệ thống hỗ trợ khách hàng thông minh
+ */
+class SmartCustomerSupport {
+  private zalo: ZaloSDK;
+  private accessToken: string;
+
+  constructor(zalo: ZaloSDK, accessToken: string) {
+    this.zalo = zalo;
+    this.accessToken = accessToken;
+  }
+
+  /**
+   * Xử lý câu hỏi của khách hàng
+   */
+  async handleCustomerQuestion(userId: string, question: string) {
+    console.log(`\n📞 Xử lý câu hỏi từ user ${userId}: "${question}"`);
+
+    try {
+      // Phân tích câu hỏi và tạo phản hồi
+      const response = this.analyzeQuestion(question);
+      
+      // Gửi tin nhắn phản hồi
+      await this.zalo.consultation.sendTextMessage(
+        this.accessToken,
+        { user_id: userId },
+        {
+          type: "text",
+          text: response.text
+        }
+      );
+
+      // Gửi thêm tài liệu hỗ trợ nếu cần
+      if (response.needsDocument) {
+        await this.sendSupportDocument(userId, response.documentType);
+      }
+
+      console.log("✅ Đã phản hồi khách hàng thành công!");
+
+    } catch (error) {
+      console.error("❌ Lỗi xử lý câu hỏi khách hàng:", error);
+      
+      // Gửi tin nhắn lỗi cho khách hàng
+      await this.sendErrorMessage(userId);
+    }
+  }
+
+  /**
+   * Phân tích câu hỏi và tạo phản hồi
+   */
+  private analyzeQuestion(question: string) {
+    const lowerQuestion = question.toLowerCase();
+
+    if (lowerQuestion.includes("đăng nhập") || lowerQuestion.includes("login")) {
+      return {
+        text: "Để đăng nhập vào hệ thống, bạn vui lòng:\n1. Truy cập trang đăng nhập\n2. Nhập email và mật khẩu\n3. Nhấn 'Đăng nhập'\n\nNếu quên mật khẩu, bạn có thể sử dụng chức năng 'Quên mật khẩu'.",
+        needsDocument: true,
+        documentType: "login_guide"
+      };
+    }
+
+    if (lowerQuestion.includes("thanh toán") || lowerQuestion.includes("payment")) {
+      return {
+        text: "Chúng tôi hỗ trợ các phương thức thanh toán sau:\n• Thẻ tín dụng/ghi nợ\n• Ví điện tử (MoMo, ZaloPay)\n• Chuyển khoản ngân hàng\n• Thanh toán khi nhận hàng (COD)\n\nBạn cần hỗ trợ về phương thức nào?",
+        needsDocument: true,
+        documentType: "payment_guide"
+      };
+    }
+
+    if (lowerQuestion.includes("giao hàng") || lowerQuestion.includes("shipping")) {
+      return {
+        text: "Thông tin về giao hàng:\n• Nội thành: 1-2 ngày\n• Ngoại thành: 2-3 ngày\n• Tỉnh khác: 3-5 ngày\n\nPhí ship được tính theo khoảng cách và trọng lượng đơn hàng.",
+        needsDocument: false,
+        documentType: null
+      };
+    }
+
+    // Phản hồi mặc định
+    return {
+      text: "Cảm ơn bạn đã liên hệ! Tôi đã ghi nhận câu hỏi của bạn. Đội ngũ hỗ trợ sẽ phản hồi trong vòng 24 giờ.\n\nCác vấn đề phổ biến:\n• Đăng nhập\n• Thanh toán\n• Giao hàng\n• Đổi trả\n\nBạn có thể hỏi cụ thể về các vấn đề này để được hỗ trợ nhanh hơn.",
+      needsDocument: false,
+      documentType: null
+    };
+  }
+
+  /**
+   * Gửi tài liệu hỗ trợ
+   */
+  private async sendSupportDocument(userId: string, documentType: string) {
+    const documents = {
+      login_guide: {
+        url: "https://example.com/guides/login-guide.pdf",
+        filename: "Hướng dẫn đăng nhập.pdf"
+      },
+      payment_guide: {
+        url: "https://example.com/guides/payment-guide.pdf", 
+        filename: "Hướng dẫn thanh toán.pdf"
+      }
+    };
+
+    const doc = documents[documentType as keyof typeof documents];
+    if (!doc) return;
+
+    await this.zalo.consultation.sendFileMessage(
+      this.accessToken,
+      { user_id: userId },
+      {
+        type: "file",
+        url: doc.url,
+        filename: doc.filename,
+        attachment: {
+          type: "file",
+          payload: {
+            url: doc.url
+          }
+        }
+      }
+    );
+  }
+
+  /**
+   * Gửi tin nhắn lỗi
+   */
+  private async sendErrorMessage(userId: string) {
+    try {
+      await this.zalo.consultation.sendTextMessage(
+        this.accessToken,
+        { user_id: userId },
+        {
+          type: "text",
+          text: "Xin lỗi, hiện tại hệ thống đang gặp sự cố. Vui lòng thử lại sau hoặc liên hệ hotline: 1900-xxxx để được hỗ trợ trực tiếp."
+        }
+      );
+    } catch (error) {
+      console.error("❌ Không thể gửi tin nhắn lỗi:", error);
+    }
+  }
+}
+
+/**
+ * Ví dụ 5: Retry mechanism
+ */
+async function sendWithRetry(
+  userId: string, 
+  message: string, 
+  maxRetries: number = 3
+): Promise<SendMessageResponse | null> {
+  console.log(`\n🔄 Gửi tin nhắn với retry (tối đa ${maxRetries} lần)`);
+  
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      console.log(`Lần thử ${attempt}/${maxRetries}`);
+      
+      const response = await zalo.consultation.sendTextMessage(
+        ACCESS_TOKEN,
+        { user_id: userId },
+        { type: "text", text: message }
+      );
+
+      console.log("✅ Gửi thành công!");
+      return response;
+
+    } catch (error) {
+      console.log(`❌ Lần thử ${attempt} thất bại:`, error instanceof ZaloSDKError ? error.message : error);
+      
+      if (attempt === maxRetries) {
+        console.log("❌ Đã thử hết số lần cho phép");
+        return null;
+      }
+
+      // Đợi trước khi thử lại (exponential backoff)
+      const delay = Math.pow(2, attempt) * 1000;
+      console.log(`⏳ Đợi ${delay}ms trước khi thử lại...`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Ví dụ 6: Tích hợp với webhook
+ */
+function setupWebhookIntegration() {
+  console.log("\n🔗 Thiết lập tích hợp webhook");
+  
+  const customerSupport = new SmartCustomerSupport(zalo, ACCESS_TOKEN);
+
+  // Giả lập xử lý webhook event
+  const handleWebhookEvent = async (event: any) => {
+    console.log("📨 Nhận webhook event:", event.event_name);
+
+    switch (event.event_name) {
+      case "user_send_text":
+        const userId = event.sender.id;
+        const userMessage = event.message.text;
+        
+        // Kiểm tra xem có phải câu hỏi cần hỗ trợ không
+        if (userMessage.includes("help") || 
+            userMessage.includes("hỗ trợ") ||
+            userMessage.includes("support")) {
+          
+          await customerSupport.handleCustomerQuestion(userId, userMessage);
+        }
+        break;
+
+      case "user_send_sticker":
+        // Phản hồi sticker bằng tin nhắn thân thiện
+        await zalo.consultation.sendTextMessage(
+          ACCESS_TOKEN,
+          { user_id: event.sender.id },
+          {
+            type: "text", 
+            text: "Cảm ơn bạn! 😊 Tôi có thể hỗ trợ gì cho bạn không?"
+          }
+        );
+        break;
+
+      default:
+        console.log("Event không cần xử lý:", event.event_name);
+    }
+  };
+
+  return handleWebhookEvent;
+}
+
+/**
+ * Chạy tất cả ví dụ
+ */
+async function runAllExamples() {
+  console.log("🚀 Bắt đầu chạy các ví dụ ConsultationService\n");
+
+  // Ví dụ cơ bản
+  await basicConsultationExample();
+  await imageConsultationExample();
+  await fileConsultationExample();
+
+  // Ví dụ hệ thống hỗ trợ thông minh
+  const customerSupport = new SmartCustomerSupport(zalo, ACCESS_TOKEN);
+  await customerSupport.handleCustomerQuestion("user123", "Tôi không đăng nhập được");
+  await customerSupport.handleCustomerQuestion("user456", "Làm sao để thanh toán?");
+
+  // Ví dụ retry
+  await sendWithRetry("user789", "Tin nhắn test retry");
+
+  // Thiết lập webhook
+  const webhookHandler = setupWebhookIntegration();
+  
+  // Giả lập một số webhook events
+  await webhookHandler({
+    event_name: "user_send_text",
+    sender: { id: "user123" },
+    message: { text: "Tôi cần hỗ trợ về đăng nhập" }
+  });
+
+  console.log("\n✅ Hoàn thành tất cả ví dụ!");
+}
+
+// Chạy ví dụ nếu file được execute trực tiếp
+if (require.main === module) {
+  runAllExamples().catch(console.error);
+}
+
+export {
+  basicConsultationExample,
+  imageConsultationExample,
+  fileConsultationExample,
+  SmartCustomerSupport,
+  sendWithRetry,
+  setupWebhookIntegration,
+  runAllExamples
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "version": "1.1.1",
-  "description": "Zalo API SDK for TypeScript/JavaScript - Comprehensive SDK for Zalo Official Account, ZNS, and Social APIs",
+  "version": "1.2.0",
+  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging, and Social APIs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -9,6 +9,11 @@
     "dev": "tsc --watch",
     "clean": "rimraf dist",
     "prepublishOnly": "npm run clean && npm run build",
+    "publish:npm": "npm publish --access public",
+    "publish:beta": "npm publish --tag beta --access public",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
     "test": "jest",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix"
@@ -21,13 +26,16 @@
     "zalo-sdk",
     "typescript",
     "official-account",
-    "notification-service"
+    "notification-service",
+    "consultation-service",
+    "customer-support",
+    "messaging"
   ],
   "author": "RedAI Team",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/redai/redai-zalo-sdk.git"
+    "url": "https://github.com/warriorteam/redai-zalo-sdk.git"
   },
   "bugs": {
     "url": "https://github.com/redai/redai-zalo-sdk/issues"
@@ -53,8 +61,10 @@
     "README.md",
     "LICENSE",
     "docs/**/*",
+    "examples/**/*",
     "ARCHITECTURE.md",
-    "SERVICES_ADDED.md"
+    "SERVICES_ADDED.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=16.0.0"