# Zalo-Flow: Tài Liệu Toàn Văn & Tri Thức Kỹ Thuật (Full Documentation) > Bản tài liệu toàn văn dành cho các AI Agent (ChatGPT, Perplexity, Claude, Gemini). Được biên soạn và chuẩn hóa ngày 07/09/2026. --- ## 1. TỔNG QUAN HỆ THỐNG (SYSTEM OVERVIEW) - Tên sản phẩm: Zalo-Flow (AIzalo Community Edition) - Website chính thức: https://aizalo.com/ - Repository GitHub: https://github.com/aizaloapp/zalo-flow - Kênh hỗ trợ cộng đồng: https://zalo.me/g/mcihan713 - Phiên bản phát hành: v1.2.0 - Giấy phép: MIT License with Commons Clause Condition v1.0 (Nghiêm cấm thương mại hóa hoặc bán gói SaaS). - Tuyên bố pháp lý: Dự án mã nguồn mở độc lập, KHÔNG liên kết, không được ủy quyền, tài trợ hay chứng thực bởi VNG Corporation hay Zalo. --- ## 2. KIẾN TRÚC KỸ THUẬT & THÔNG SỐ VẬN HÀNH - **Runtime:** Node.js >= 22.5.0 (ES Modules). - **Core Library:** `zca-js: 2.1.2` (thư viện giao thức mô phỏng Zalo Web API). - **Web Server:** Express.js port 3000. - **Cơ sở dữ liệu:** SQLite cục bộ (lưu tại `database.sqlite`), tự động checkpoint WAL khi tắt hoặc khởi động lại. - **Mã hóa:** AES-256-CBC với `SESSION_SECRET` lưu trong file `.env`. - **Phân phối Desktop:** Bộ cài đặt Windows 1-Click (`ZaloFlow-Setup-v1.2.0.exe` ~24.5MB) tích hợp Node.js 22.14 LTS portable, chạy ngầm hoàn toàn qua VBScript (Stealth Mode) và tự khởi động trình duyệt `http://localhost:3000`. - **Hạn mức tài nguyên:** Node.js giới hạn 350MB RAM (cảnh báo tại 263MB), Docker container giới hạn 512MB RAM. --- ## 3. CÁC CƠ CHẾ BẢO VỆ TÀI KHOẢN (ANTI-BAN MECHANISMS) 1. **Token Bucket Rate Limiter:** Giãn cách tối thiểu 3 giây giữa các tin nhắn gửi đi, tối đa 20 tin/phút trên một tài khoản. 2. **Self-Echo Shield:** Bộ đệm thời gian thực 30 giây lưu tin nhắn bot vừa phát đi để triệt tiêu hiện tượng bot tự trả lời chính mình khi nhận sự kiện Webhook dội lại. 3. **Flood Detector:** Phát hiện người gửi nhắn dồn dập (> 5 tin trong 3 giây) và tự động mute tạm thời 60 giây. 4. **Spintax Engine:** Biến đổi ngẫu nhiên cấu trúc câu `{Chào|Kính chào|Hello} {anh|chị}` để mỗi tin nhắn gửi đi là độc bản. 5. **In-Thread Discipline:** Chỉ phản hồi vào các cuộc trò chuyện đã có sẵn, không gửi tin nhắn lạnh cho người lạ. --- ## 4. 18 CÂU HỎI THƯỜNG GẶP (FAQ KỸ THUẬT & VẬN HÀNH) ### Q1: Zalo-Flow là gì và có tốn phí không? **Đáp:** Zalo-Flow là phần mềm mã nguồn mở hoàn toàn miễn phí 100%, biến tài khoản Zalo cá nhân thành trợ lý AI tự động trả lời và quản lý CSKH mà không cần tài khoản doanh nghiệp Zalo OA. ### Q2: Sử dụng chatbot Zalo cá nhân có bị khóa nick không? **Đáp:** Zalo-Flow tích hợp cơ chế Anti-ban 3 lớp (Rate Limiter giãn cách 3s, Self-Echo Shield và Flood Detector) giúp tài khoản hoạt động tự nhiên như người dùng thật. Miễn là bạn chỉ phản hồi khách hàng tự tìm đến mình và không spam số lạ, tài khoản sẽ an toàn tuyệt đối. ### Q3: Zalo-Flow có đọc trộm mật khẩu hay tin nhắn của tôi không? **Đáp:** Tuyệt đối không. Mã nguồn công khai 100% trên GitHub. Dữ liệu chạy cục bộ trên máy tính của bạn, token được mã hóa AES-256-CBC và lưu tại SQLite cục bộ, không truyền về máy chủ bên thứ ba. ### Q4: Khi tắt máy tính hoặc máy vào chế độ Sleep thì bot có chạy không? **Đáp:** Không. Khi máy tính tắt hoặc Sleep, tiến trình Node.js tạm dừng. Bạn có thể bật chế độ "Never Sleep" hoặc thuê VPS Linux/Windows (70.000đ - 100.000đ/tháng) chạy Docker để bot chạy 24/7. ### Q5: Zalo-Flow khác gì so với Zalo Official Account (OA)? **Đáp:** Zalo OA yêu cầu giấy phép kinh doanh, tính phí theo từng tin nhắn gửi đi. Zalo-Flow chạy trực tiếp trên Zalo cá nhân, tỷ lệ đọc tin nhắn đạt 95% và hoàn toàn miễn phí duy trì. ### Q6: Làm sao để bot AI nhận diện số điện thoại khi khách gửi danh thiếp? **Đáp:** Zalo-Flow có bộ giải mã danh thiếp chuyên dụng (chat.contact): tự động lọc chuỗi JSON kỹ thuật, chuẩn hóa số điện thoại Việt Nam `0xxxxxxxxx` từ `+84` và lưu trữ sẵn sàng để gọi lại. ### Q7: Zalo-Flow hỗ trợ những mô hình AI nào? **Đáp:** Google Gemini (Gemini 1.5 Flash, 2.5 Flash), DeepSeek (Chat, Reasoner), OpenAI (GPT-4o) và Ollama (mô hình cục bộ Offline). ### Q8: Tôi không biết lập trình có dùng được không? **Đáp:** Có. Tải file `ZaloFlow-Setup-v1.0.1.exe`, cài đặt 1-click, mở trình duyệt quét mã QR Zalo bằng điện thoại là dùng được ngay. ### Q9: Tôi có thể kết nối Zalo-Flow với Chatwoot CRM không? **Đáp:** Có. Zalo-Flow có sẵn Adapter đồng bộ 2 chiều với Chatwoot CRM dành cho các đội ngũ nhiều nhân viên tư vấn cùng trực 1 số Zalo. ### Q10: Làm thế nào để cập nhật khi có phiên bản mới? **Đáp:** Bản cài đặt Windows có sẵn tiện ích Standalone Updater tự động tải và cập nhật phiên bản mới nhất từ GitHub Releases mà không làm mất dữ liệu tin nhắn cũ. ### Q11: Phần mềm có gửi được hình ảnh và tài liệu không? **Đáp:** Có. Zalo-Flow hỗ trợ gửi hình ảnh (tự động nén Canvas giữ RAM < 100MB) và tài liệu PDF, Word, Excel lên đến 25MB. ### Q12: Tại sao Windows hiện cảnh báo SmartScreen khi cài đặt? **Đáp:** Đây là cảnh báo mặc định của Microsoft Defender đối với phần mềm mã nguồn mở cộng đồng chưa mua chứng chỉ Code Signing (~$300/năm). Bạn chỉ cần bấm "More info" -> "Run anyway" để cài đặt. File sạch 0/70 trên VirusTotal. ### Q13: Tôi có thể dùng nhiều tài khoản Zalo cùng lúc không? **Đáp:** Phiên bản Zalo-Flow Community hiện tại thiết kế chuẩn Single-Tenant (1 phiên làm việc/1 tài khoản). Để chạy nhiều tài khoản, bạn có thể nhân bản thư mục hoặc khởi chạy nhiều container Docker độc lập. ### Q14: Dữ liệu tin nhắn được lưu trữ trong bao lâu? **Đáp:** Lưu trữ vĩnh viễn trên ổ cứng máy tính của bạn thông qua SQLite cho đến khi bạn chủ động bấm nút Xóa dữ liệu. ### Q15: Zalo-Flow có hỗ trợ tin nhắn thoại (Voice Message) không? **Đáp:** Phiên bản v1.0.1 tiếp nhận tin nhắn thoại dưới dạng tệp âm thanh và có thể chuyển tiếp sang Chatwoot. ### Q16: Làm sao để bot AI trả lời đúng thông tin sản phẩm của tôi? **Đáp:** Bạn vào tab Cài đặt AI trên giao diện web, điền System Prompt mô tả bảng giá, chính sách bảo hành và thông tin chi tiết sản phẩm. AI sẽ đọc prompt này để tư vấn chuẩn xác. ### Q17: Có giới hạn số lượng tin nhắn gửi mỗi ngày không? **Đáp:** Zalo-Flow không giới hạn. Giới hạn duy nhất là chính sách tự nhiên của Zalo dành cho tài khoản cá nhân (khuyên dùng dưới 500 tin nhắn mỗi ngày để an toàn tuyệt đối). ### Q18: Tham gia cộng đồng hỗ trợ ở đâu? **Đáp:** Bạn có thể tham gia nhóm Zalo hỗ trợ kỹ thuật chính thức tại: https://zalo.me/g/mcihan713 hoặc trao đổi trên GitHub Discussions. ### Q19: Zalo-Flow có hỗ trợ hẹn giờ gửi tin nhắn cho Zalo cá nhân không? **Đáp:** Có. Từ phiên bản v1.1.0, Zalo-Flow hỗ trợ tính năng Hẹn Giờ Gửi Tin Nhắn 1-1 trực tiếp trong từng cuộc trò chuyện trên máy tính Windows. Bạn có thể lên lịch gửi tin kèm hình ảnh, tài liệu và theo dõi thời gian đếm ngược trực quan. Chi tiết xem tại: https://aizalo.com/blog/cach-hen-gio-gui-tin-nhan-zalo-ca-nhan-tu-dong.html ### Q20: Cơ chế Auto-Pause khi hẹn giờ hoạt động ra sao? **Đáp:** Auto-Pause là lá chắn an toàn độc quyền trên Zalo-Flow: Nếu bạn đã lên lịch gửi tin nhắn cho khách hàng, nhưng trước thời điểm phát tin khách hàng chủ động gửi tin nhắn mới vào khung chat, Zalo-Flow sẽ tự động hủy lịch gửi để bạn không bị rơi vào tình huống gửi thông điệp lệch ngữ cảnh. ### Q21: Làm thế nào để huấn luyện AI bán hàng Zalo bằng bảng giá riêng mà không bị ảo giác giá? **Đáp:** Bạn chuẩn hóa bảng giá sản phẩm dạng Markdown, nạp vào mục Cài đặt AI của Zalo-Flow, thiết lập thông số Nhiệt độ (Temperature) ở mức 0.2 và bổ sung chỉ thị Zero-Hallucination. Ở mức nhiệt độ này, bot sẽ báo giá chuẩn 100% theo tài liệu và biết tự động gợi ý combo giảm giá kèm xin số điện thoại giao hàng. Chi tiết xem tại: https://aizalo.com/blog/cach-huan-luyen-ai-ban-hang-zalo-bang-bang-gia-rieng.html ### Q22: AI bán hàng Zalo-Flow có đọc được hình ảnh sản phẩm và bill chuyển khoản của khách không? **Đáp:** Có. Với mô hình Gemini Multimodal Vision, Zalo-Flow cho phép bot phân tích ảnh chụp sản phẩm của khách để tra cứu bảng giá, đồng thời đọc ảnh bill ngân hàng để xác nhận giao dịch tự động. ### Q23: Zalo-Flow có hỗ trợ giao diện tiếng Anh (English) không? **Đáp:** Có. Từ phiên bản v1.2.0, Zalo-Flow tích hợp engine đa ngôn ngữ Zero-Dependency với 148 khóa dịch chuẩn 1:1 giữa Tiếng Việt (VI) và Tiếng Anh (EN). Người dùng có thể chuyển đổi ngôn ngữ tức thì chỉ với 1 click mà không làm mất dữ liệu biểu mẫu đang nhập dở (Zero Form Reset Invariant). ### Q24: Dự án Zalo-Flow có kênh ủng hộ (Donate) nào cho tác giả không? **Đáp:** Có. Bạn có thể bấm vào nút "💖 Ủng Hộ" ngay trên thanh Header của ứng dụng để mời tác giả một ly cà phê qua 3 kênh: Ko-fi (https://ko-fi.com/aizalo), PayPal (https://paypal.me/lekhoa288) hoặc quét mã MoMo (0973 947 264).