pos-system/microservices/services/mkt-whatsapp-service-net/docs/vi/AUTOMATION_GUIDE.md

Hướng Dẫn Automation

Cập nhật lần cuối: 2026-01-18

Tìm hiểu cách tạo và quản lý luồng tự động cho hội thoại WhatsApp.

Tổng Quan

Luồng tự động cho phép bạn định nghĩa logic chatbot dựa trên quy tắc mà không cần AI. Các trường hợp sử dụng bao gồm:

• Tin nhắn chào mừng khách hàng mới
• Tự động trả lời FAQ
• Luồng xác nhận đơn hàng
• Khảo sát tiềm năng khách hàng
• Đặt lịch hẹn
• Định tuyến hỗ trợ khách hàng

Khái Niệm Cốt Lõi

Các Loại Trigger

Trigger	Mô Tả	Ví dụ
Keyword	Tin nhắn chứa văn bản cụ thể	"hi", "help", "price"
Event	Sự kiện hệ thống xảy ra	Khách hàng opt in, đơn hàng được tạo
Schedule	Kích hoạt dựa trên thời gian	Hàng ngày lúc 9 giờ sáng, mỗi thứ Hai

Các Bước Luồng

Mỗi luồng bao gồm các bước theo thứ tự. Các loại bước:

1. Gửi Tin Nhắn

• Gửi tin nhắn văn bản hoặc media
• Hỗ trợ biến: {customer_name}, {shop_name}

2. Trả Lời Nhanh

• Hiển thị nút để khách hàng nhấn
• Phân nhánh đến các bước khác nhau dựa trên lựa chọn

3. Gắn Tag Khách Hàng

• Thêm/xóa tags khách hàng
• Sử dụng để phân khúc

4. Gọi Webhook

• POST dữ liệu đến URL bên ngoài
• Tích hợp với CRM, hệ thống kho

5. Gán Cho Nhân Viên

• Chuyển hội thoại đến nhân viên
• Thoát tự động

6. Trì Hoãn

• Chờ trước bước tiếp theo
• Thời gian tính bằng giây/phút/giờ

7. Phân Nhánh Có Điều Kiện

• Logic if/else
• Điều kiện: tag tồn tại, giá trị trường tùy chỉnh, giờ trong ngày

Tạo Luồng

Qua API

POST /api/v1/whatsapp/flows
Content-Type: application/json

{
  "shopId": "shop-guid",
  "flowName": "Chào Mừng Khách Hàng Mới",
  "triggerType": "keyword",
  "triggerConfig": {
    "keywords": ["hi", "hello", "start", "chào", "xin chào"]
  },
  "steps": [
    {
      "order": 1,
      "action": "send_message",
      "actionConfig": {
        "text": "Chào mừng đến {shop_name}! 👋\\n\\nChúng tôi có thể giúp gì cho bạn hôm nay?"
      }
    },
    {
      "order": 2,
      "action": "quick_reply",
      "actionConfig": {
        "text": "Chọn một tùy chọn:",
        "buttons": [
          {"id": "browse", "title": "Xem Sản Phẩm"},
          {"id": "track", "title": "Tra Đơn Hàng"},
          {"id": "support", "title": "Hỗ Trợ"}
        ]
      },
      "nextStepMapping": {
        "browse": 3,
        "track": 5,
        "support": 7
      }
    },
    {
      "order": 3,
      "action": "send_message",
      "actionConfig": {
        "text": "Truy cập catalog của chúng tôi: https://shop.example.com"
      }
    }
  ]
}

Phản Hồi

{
  "success": true,
  "data": {
    "flowId": "flow-guid",
    "flowName": "Chào Mừng Khách Hàng Mới",
    "isActive": false,
    "createdAt": "2026-01-18T10:00:00Z"
  }
}

Ví Dụ Luồng

Ví Dụ 1: FAQ Bot

Trigger: Từ khóa "giá", "bao nhiêu", "price", "cost"

Luồng:

1. Gửi: "Giá của chúng tôi phụ thuộc vào sản phẩm. Bạn quan tâm đến sản phẩm nào?"
2. Trả Lời Nhanh: ["Thời Trang", "Điện Tử", "Thực Phẩm"]
3. Điều Kiện:
   • Nếu "Thời Trang" → Gửi bảng giá thời trang
   • Nếu "Điện Tử" → Gửi bảng giá điện tử
   • Nếu "Thực Phẩm" → Gửi bảng giá thực phẩm

Ví Dụ 2: Đặt Lịch Hẹn

Trigger: Từ khóa "lịch hẹn", "đặt lịch", "appointment"

Luồng:

1. Gửi: "Tôi có thể giúp bạn đặt lịch hẹn! 📅"
2. Gửi: "Bạn cần dịch vụ gì?"
3. Trả Lời Nhanh: ["Tư Vấn", "Kiểm Tra", "Tái Khám"]
4. Gắn Tag Khách Hàng: "appointment-pending"
5. Gọi Webhook: POST đến hệ thống đặt lịch
6. Trì Hoãn: 2 giây (chờ phản hồi webhook)
7. Gửi: "Lịch hẹn của bạn đã được xác nhận! Bạn sẽ nhận được nhắc nhở."

Ví Dụ 3: Tra Cứu Đơn Hàng

Trigger: Từ khóa "tra", "đơn hàng", "track", "order status"

Luồng:

1. Gửi: "Vui lòng gửi mã đơn hàng của bạn (ví dụ: #12345)"
2. (Khách hàng trả lời với mã đơn hàng)
3. Gọi Webhook: GET trạng thái đơn hàng từ backend
4. Điều Kiện:
   • Nếu tìm thấy đơn → Gửi trạng thái + link theo dõi
   • Nếu không tìm thấy → Gửi "Không tìm thấy đơn hàng. Vui lòng kiểm tra lại mã."

Biến

Sử dụng biến trong văn bản tin nhắn để cá nhân hóa:

Biến Khách Hàng

• {customer_name} - Tên khách hàng
• {customer_phone} - Số WhatsApp của khách hàng
• {customer_tags} - Tags phân cách bằng dấu phẩy

Biến Cửa Hàng

• {shop_name} - Tên cửa hàng
• {shop_url} - URL website cửa hàng

Biến Hội Thoại

• {conversation_id} - UUID hội thoại
• {message_count} - Số lượng tin nhắn trong hội thoại

Biến Tùy Chỉnh (từ phản hồi webhook)

Webhook có thể trả về biến:

{
  "variables": {
    "order_status": "Đã Gửi",
    "tracking_number": "ABC123XYZ"
  }
}

Sử dụng trong bước tiếp theo:

Đơn hàng của bạn đang {order_status}. Theo dõi tại đây: {tracking_number}

Điều Kiện

Các Điều Kiện Được Hỗ Trợ

Tag Tồn Tại

{
  "type": "tag_exists",
  "tag": "vip-customer"
}

Trường Tùy Chỉnh Bằng

{
  "type": "custom_field_equals",
  "field": "city",
  "value": "Hanoi"
}

Giờ Trong Ngày

{
  "type": "time_of_day",
  "start": "09:00",
  "end": "17:00",
  "timezone": "Asia/Ho_Chi_Minh"
}

Ngày Trong Tuần

{
  "type": "day_of_week",
  "days": ["monday", "tuesday", "wednesday"]
}

Tin Nhắn Chứa

{
  "type": "message_contains",
  "text": "khẩn cấp",
  "case_sensitive": false
}

Kết Hợp Điều Kiện

Sử dụng logic AND/OR:

{
  "type": "and",
  "conditions": [
    {"type": "tag_exists", "tag": "vip-customer"},
    {"type": "time_of_day", "start": "00:00", "end": "23:59"}
  ]
}

Kích Hoạt Luồng

POST /api/v1/whatsapp/flows/{flowId}/activate

Phản Hồi:

{
  "success": true,
  "data": {
    "flowId": "flow-guid",
    "isActive": true,
    "activatedAt": "2026-01-18T10:05:00Z"
  }
}

Ưu Tiên

Khi nhiều luồng khớp, ưu tiên xác định luồng nào thực thi:

1. Khớp từ khóa chính xác (ưu tiên cao nhất)
2. Event triggers
3. Scheduled triggers (ưu tiên thấp nhất)

Đặt ưu tiên khi tạo luồng:

{
  "flowName": "Chào Mừng Khách Hàng VIP",
  "priority": 100,
  ...
}

Số lớn hơn = ưu tiên cao hơn (mặc định: 50)

Kiểm Tra Luồng

Chế Độ Kiểm Tra

Bật chế độ kiểm tra để xem quá trình thực thi mà không gửi tin nhắn thực tế:

POST /api/v1/whatsapp/flows/{flowId}/test
Content-Type: application/json

{
  "shopId": "shop-guid",
  "customerWaId": "84901234567",
  "simulatedMessage": "xin chào"
}

Phản Hồi:

{
  "success": true,
  "data": {
    "matched": true,
    "executedSteps": [
      {"step": 1, "action": "send_message", "result": "Sẽ gửi: Chào mừng..."},
      {"step": 2, "action": "quick_reply", "result": "Sẽ hiển thị nút"}
    ]
  }
}

Nhật Ký Debug

Xem lịch sử thực thi luồng:

GET /api/v1/whatsapp/flows/{flowId}/executions?limit=20

Thực Hành Tốt Nhất

1. Giữ Luồng Đơn Giản

• Tối đa 10 bước mỗi luồng
• Tránh lồng sâu các điều kiện
• Chia luồng phức tạp thành nhiều luồng nhỏ hơn

2. Cung Cấp Điểm Thoát

Luôn cho khách hàng cách để:

• Nói chuyện với nhân viên ("support", "help", "hỗ trợ")
• Bắt đầu lại ("restart", "menu", "khởi động lại")
• Hủy đăng ký ("stop", "unsubscribe", "dừng")

3. Xử Lý Đầu Vào Không Xác Định

Thêm bước dự phòng:

{
  "order": 99,
  "action": "send_message",
  "actionConfig": {
    "text": "Tôi không hiểu. Trả lời 'menu' để xem tùy chọn hoặc 'hỗ trợ' để nói chuyện với nhân viên."
  }
}

4. Sử Dụng Trì Hoãn Khôn Ngoan

• Sau lời gọi webhook: 2-5 giây
• Giữa các tin nhắn: 1-2 giây (tự nhiên hơn)
• Tránh trì hoãn > 10 giây (khách hàng có thể rời đi)

5. Kiểm Thử A/B

Tạo hai phiên bản của luồng:

• Luồng A: Gửi biến thể tin nhắn A
• Luồng B: Gửi biến thể tin nhắn B

Định tuyến 50% lưu lượng cho mỗi luồng, đo lường:

• Tỷ lệ phản hồi
• Tỷ lệ chuyển đổi
• Thời gian giải quyết

Giới Hạn

• Tối đa 50 luồng hoạt động mỗi cửa hàng
• Tối đa 20 bước mỗi luồng
• Tối đa 10 nút trả lời nhanh mỗi tin nhắn
• Timeout webhook: 10 giây
• Không có vòng lặp (xác thực chống chu trình)

Khắc Phục Sự Cố

Luồng Không Kích Hoạt

Kiểm Tra:

1. Luồng đã được kích hoạt (isActive: true)
2. Từ khóa trigger khớp chính xác (không phân biệt chữ hoa/thường)
3. Không có luồng ưu tiên cao hơn khớp trước
4. Khách hàng chưa hủy đăng ký

Webhook Thất Bại

Kiểm Tra:

1. URL webhook có thể truy cập (yêu cầu HTTPS)
2. Webhook phản hồi trong vòng 10 giây
3. Mã trạng thái phản hồi là 200
4. JSON phản hồi hợp lệ

Biến Không Được Thay Thế

Kiểm Tra:

1. Cú pháp biến đúng: {variable_name}
2. Biến được định nghĩa (customer_name tồn tại cho khách hàng)
3. Webhook trả về các biến mong đợi

Bước Tiếp Theo

• Hướng Dẫn AI Chatbot - Kết hợp với AI cho cách tiếp cận lai
• Tài Liệu API - Tham chiếu API đầy đủ
• Kiến Trúc - Hiểu về công cụ tự động

Tài Nguyên

• Giao Diện Flow Builder (nếu có)
• Hướng Dẫn Tích Hợp Webhook