@warriorteam/redai-zalo-sdk 1.1.1 → 1.3.0

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