📺 Video hướng dẫn cài đặt & đăng nhập Zalo trên n8n

Video chi tiết cách cài đặt node, cấu hình và đăng nhập Zalo bằng QR code trên n8n.

n8n-nodes-zalo-nnt

Node dành riêng cho n8n này được thiết kế hoạt động hoàn toàn bên trong instance n8n của bạn. Không cần sử dụng API của bên thứ ba hay phụ thuộc ngoại vi nào — chỉ có sự tự động hóa quy trình thuần túy, đảm bảo dữ liệu của bạn luôn được giữ riêng tư và an toàn.

Node này mô phỏng trình duyệt để tương tác trực tiếp với Zalo Web, cho phép tự động hóa liền mạch ngay trong n8n. Đây là dự án mã nguồn mở, mở rộng cơ hội cho cộng đồng cùng đóng góp ý kiến và phát triển thêm các tính năng mới, nhằm xây dựng hệ thống tự động hóa Zalo tiên tiến, hiệu quả và an toàn hơn.

🎉 Version 1.1.9 - QR Login Fix & New APIs

✅ Bug Fixes

• QR Login: Fixed cookie format issue - credentials now save correctly and can be used by other nodes
• zalo-js v2.1.2: Includes cookie domain fix (PR #255) for better session persistence

✨ New APIs

ZaloGroup

• getGroupChatHistory - Lấy lịch sử chat nhóm với phân trang

ZaloUser (5 new operations)

• getCloseFriends - Lấy danh sách bạn thân
• findUserByUsername - Tìm người dùng theo username Zalo
• getMultiUsersByPhones - Tìm nhiều user theo số điện thoại (tối đa 50 số)
• getAvatarUrlProfile - Lấy URL avatar profile
• getFullAvatar - Lấy avatar độ phân giải đầy đủ

ZaloConversation

• updateArchivedChatList - Thêm/xóa cuộc trò chuyện khỏi danh sách lưu trữ

🔧 Improvements

• Better error handling với NodeOperationError
• Improved logging cho debugging
• 111 unit tests covering all APIs

🎉 Version 1.0.3 - Local File Support

✨ Tính năng mới

• ZaloSendMessage: Hỗ trợ gửi file từ local server (không cần URL)
  • Thêm 2 loại attachment mới: Đường dẫn Local và Mảng Đường dẫn Local
  • Tự động tìm file từ nhiều vị trí: đường dẫn tuyệt đối, thư mục n8n (~/.n8n/), hoặc working directory
  • Tích hợp liền mạch với node FTP, HTTP Request, và Read/Write Files from Disk
  • Logging chi tiết để debug đường dẫn file

🔧 Cải thiện

• Validation file path thông minh với fallback mechanism
• Hỗ trợ cả đường dẫn tuyệt đối và tương đối
• Error messages rõ ràng hơn (hiển thị tất cả đường dẫn đã tìm kiếm)
• Descriptions và placeholders được cập nhật cho user-friendly

💡 Use Case

HTTP Request (download) → Read/Write Files (save to disk) → ZaloSendMessage (send local file)
FTP Node (download) → ZaloSendMessage (send from file name: {{ $json.fileName }})

🎉 Version 1.0.2 - Maintenance Release

✅ Thay đổi

• Cập nhật cấu hình build và tài liệu bảo vệ mã nguồn trong docs/development/code-protection.md để chuẩn hoá quy trình build/obfuscate khi phát hành.
• Hoàn thiện gói dist/ sẵn sàng publish; không thay đổi API bề mặt.

ℹ️ Lý do

• Đảm bảo trải nghiệm cài đặt mượt mà khi dùng pnpm publish (tự động build + obfuscate + lint qua hook prepublishOnly).
• Đồng bộ phiên bản package.json với bản phát hành trên npm.

🎉 Version 1.0.0 - Major Release

🚀 Tổng quan

Package n8n-nodes-zalo-nnt hiện cung cấp 9 nodes với 70+ operations để tự động hóa Zalo hoàn toàn trong n8n.

📊 Thống kê

• 9 nodes: 1 trigger node + 8 action nodes
• 70+ operations tổng cộng
• 111 unit tests đảm bảo chất lượng
• 2 credential types: zaloApi (QR login) + n8nApiZaloApi

🎯 Tính năng chính v1.0.0

1. ZaloSendMessage - Gửi tin nhắn đa năng

• Markdown formatting (đậm, nghiêng, [red]màu[/red])
• Gửi nhiều ảnh/file: URL, mảng URL, hoặc đường dẫn local ⭐ NEW
• HEIC/HEIF → JPEG auto-conversion
• Quote reply (trích dẫn tin nhắn)
• @Mention users (gắn thẻ)
• Độ ưu tiên: Mặc định, Quan trọng, Khẩn cấp
• TTL (tự xóa tin nhắn sau X giây)
• Local file support: Gửi trực tiếp từ FTP/HTTP download hoặc Read/Write Files node ⭐ NEW
• Gửi danh thiếp (card), thẻ ngân hàng, link kèm xem trước, tin nhắn thoại
• Chỉ tải lên tệp lên server Zalo (không gửi tin nhắn) để lấy URL dùng lại

2. ZaloGroup - Quản lý nhóm toàn diện (38 ops)

7 Resources:

• Nhóm: Tạo, lấy info, danh sách, tham gia, rời
• Thành viên: Thêm, xóa, thay thế, mời nhiều nhóm, thêm/gỡ phó nhóm, chuyển quyền trưởng nhóm, lấy thông tin chi tiết thành viên
• Tạo/thêm/xóa/thay thành viên chấp nhận danh sách trộn UID và SĐT; SĐT được tự động tìm UID trước khi xử lý
• Mapping SĐT → UID được trả trong output để audit và sẽ xuất hiện trong execution log của n8n
• Cài đặt: Đổi tên, đổi avatar, nâng cấp lên cộng đồng
• Kiểm duyệt: Lấy DS chặn, chặn/bỏ chặn, duyệt yêu cầu
• Nội dung: Tạo ghi chú (có ghim), lấy lịch sử chat
• Link mời: Lấy thông tin/chi tiết, bật/tắt link mời
• Hộp thư mời: Lấy chi tiết/danh sách lời mời, tham gia, xóa/từ chối lời mời

3. ZaloChatHistory - Lịch sử trò chuyện

• Fetch all mode (tự động phân trang)
• Lọc theo thời gian (từ ngày - đến ngày)
• Sắp xếp (mới nhất/cũ nhất)
• Lấy reactions
• Delay control (tránh block)

4. ZaloReminder - Lịch hẹn thông minh

• Tạo/sửa/xóa lịch hẹn
• Lặp lại: Hàng ngày/tuần/tháng
• Emoji tùy chỉnh
• Lấy phản hồi (chấp nhận/từ chối)

5. ZaloPoll - Bình chọn

• Tạo/lấy/khóa poll
• Multi-choice, thêm option mới
• Ẩn kết quả/người vote
• Ghim poll, thời hạn
• Thêm phương án vào poll đang mở, chia sẻ lại poll, bình chọn

6. ZaloUser - Quản lý user (47 ops)

7 Resources:

• Bạn bè (15): Gửi/chấp nhận/từ chối lời mời, xóa, tìm kiếm SĐT/username, bạn thân, gợi ý kết bạn, bạn online, nhóm chung, trạng thái kết bạn
• Tài khoản (9): Lấy info, đổi settings, đổi ngôn ngữ, đổi bio, đổi avatar, lấy/cập nhật cài đặt, đổi trạng thái hoạt động
• Riêng tư (4): Chặn/bỏ chặn user, chặn xem feed, báo cáo vi phạm
• Biệt danh (3): Đổi/xóa/lấy danh sách alias
• Avatar (5): Lấy DS, dùng lại ảnh cũ, xóa, lấy URL avatar, lấy avatar full
• Tin nhắn (6): Thu hồi, thả cảm xúc, chuyển tiếp, xóa tin nhắn, gửi trạng thái đã xem/đã nhận
• Hệ thống (5): Keep alive, last online, phân tích link, kiểm tra kết nối (checkConnection — gọi API thật, không throw, dùng để check hàng loạt tài khoản sống/chết), lấy cookie phiên (getCookie — xuất session cookie hiện tại để nhân bản/di chuyển sang credential khác, ⚠️ trả về plaintext trong execution log)

7. ZaloTag - Quản lý thẻ

• Lấy danh sách labels/tags
• Cập nhật toàn bộ danh sách thẻ

8. ZaloLoginByQr - Đăng nhập tự động

• QR login đơn giản
• Auto-create credential (tích hợp n8n API)
• Proxy support
• Output QR code dạng PNG

9. ZaloMessageTrigger - Event listener (9 events)

Lắng nghe:

1. Tin nhắn mới
2. Reaction (cảm xúc)
3. Typing (đang soạn)
4. Seen/Delivered
5. Undo (thu hồi)
6. Group events (join/leave/kick/admin)
7. Friend events (request/accept/reject)
8. Connection status

Bộ lọc:

• Loại nội dung: text/image/sticker/file/link/video/voice
• Nguồn: cá nhân/nhóm
• ID cụ thể
• Self-listen mode

10. ZaloSticker - Tìm kiếm và gửi sticker

Chức năng:

• Tìm kiếm sticker theo từ khóa
• Lấy chi tiết danh mục sticker
• Lấy danh sách ID sticker theo từ khóa
• Lấy chi tiết một hoặc nhiều sticker theo ID
• Gửi sticker vào cuộc trò chuyện cá nhân hoặc nhóm

11. ZaloBusiness - Quản lý Zalo Official Account (14 ops)

4 Resources:

• Tự động trả lời (4): Tạo/cập nhật/xóa/lấy danh sách
• Danh mục (4): Tạo/cập nhật/xóa/lấy danh sách danh mục sản phẩm
• Sản phẩm (5): Tạo/cập nhật/xóa/lấy danh sách sản phẩm, tải lên ảnh sản phẩm
• Hồ sơ doanh nghiệp (1): Lấy thông tin Official Account

⚠️ Dành cho tài khoản Zalo Official Account/Business — các thao tác này rủi ro chính sách cao hơn nhắn tin thông thường, cân nhắc kỹ trước khi dùng trên tài khoản chính.

📦 Hướng dẫn cài đặt

Community Nodes (Khuyến nghị)

Đối với người dùng n8n v0.187+, bạn có thể cài đặt node này trực tiếp từ bảng Community Nodes trong trình soạn thảo n8n.

1. Mở trình soạn thảo n8n của bạn
2. Vào Settings > Community Nodes
3. Tìm kiếm "n8n-nodes-zalo-nnt"
4. Nhấp vào Install
5. Tải lại trình soạn thảo

Cài đặt thủ công

cd YOUR_N8N_INSTALLATION_DIRECTORY
npm install n8n-nodes-zalo-nnt

🔑 Credentials Setup

1. zaloApi (Zalo Credential)

Credential này được tạo tự động khi bạn sử dụng node ZaloLoginByQr.

Thông tin credential:

• cookie: JSON array of cookies từ Zalo Web
• imei: Device IMEI (auto-generated)
• userAgent: Browser user agent
• proxy: (Optional) Proxy URL nếu cần
• supportCode: (Optional) Support code
• licenseKey: (Optional) License key

2. n8nApiZaloApi (n8n API for QR Login)

Credential này cần thiết để node ZaloLoginByQr có thể tự động tạo credential Zalo sau khi đăng nhập thành công.

Cách lấy n8n API key:

1. Vào Settings > API trong n8n
2. Tạo API key mới
3. Copy API key và URL của n8n instance

🎓 Use Cases

1. Customer Support Bot

• Auto-reply tin nhắn khách hàng
• Phân loại và route requests
• Tích hợp CRM/ticketing systems

2. Marketing Automation

• Gửi tin nhắn hàng loạt
• Scheduled campaigns
• Group management tự động

3. Monitoring & Alerts

• Nhận thông báo từ hệ thống
• Alert qua Zalo group
• Status updates tự động

4. Data Collection

• Lấy lịch sử chat để phân tích
• Export group member lists
• Poll/survey automation

5. Event-Driven Workflows

• Trigger workflows từ tin nhắn Zalo
• Auto-response dựa trên nội dung
• Integration với external services

❓ FAQ & Troubleshooting

Tại sao ảnh gửi đi đôi khi bị resize?

Trả lời: Đây không phải là lỗi của node mà là tính năng của Zalo Server.

• Node của chúng ta KHÔNG resize ảnh, luôn gửi ảnh nguyên bản
• Zalo server tự động resize ảnh dựa trên file size (bytes), không phải dimension (pixels)
• Nếu file size > ngưỡng cho phép (thường ~2-5MB) → Zalo server sẽ tự động resize
• Cùng dimension nhưng khác file size → kết quả khác nhau

Giải pháp:

• Nén ảnh trước khi gửi (giảm quality xuống 80-90%)
• Giữ file size dưới 2MB
• Sử dụng JPEG thay vì PNG cho ảnh chụp
• Xem phân tích chi tiết: docs/nodes/zalo-image-resize-analysis.md

⚠️ Lưu ý quan trọng

Vui lòng đọc kỹ trước khi sử dụng:

Việc sử dụng thư viện này đồng nghĩa với việc bạn đang làm trái với chính sách của Zalo và nó có thể khiến cho tài khoản của bạn bị vô hiệu hóa. Chúng tôi sẽ không chịu trách nhiệm nếu điều đó xảy ra, vậy nên hãy cân nhắc trước khi sử dụng.

Yêu cầu môi trường:

• Chỉ chạy được trên n8n self-hosted (Node.js >= 18.10) — không hỗ trợ n8n Cloud vì package cần cài qua Community Nodes/npm trực tiếp trên instance của bạn.
• Zalo chỉ cho phép một phiên đăng nhập (một listener) cho mỗi tài khoản tại một thời điểm — chạy ZaloMessageTrigger cùng lúc với việc đăng nhập Zalo Web trên trình duyệt khác sẽ làm gián đoạn kết nối.
• Nên dùng tài khoản Zalo phụ/dùng thử để test workflow, tránh dùng tài khoản chính khi mới thiết lập.

💝 Ủng hộ tác giả

Nếu node này giúp bạn tiết kiệm thời gian hoặc giải quyết được vấn đề khó nhằn, hãy cân nhắc ủng hộ tôi tại đây hoặc thuê team chúng tôi triển khai setup workflow cho bạn -> diginno.net

Sự động viên nhỏ ấy sẽ tiếp thêm năng lượng để mình tiếp tục duy trì, cập nhật và phát triển thêm nhiều tính năng hữu ích hơn nữa. Cám ơn bạn rất nhiều! 💛

👨‍💻 Tác giả

• Nguyễn Ngô Thượng - Maintainer & Developer
• Original work by Dương Đình Trung - ChickenAI Team

🙏 Cảm ơn

We would like to thank ZCA-JS for their excellent work on the core library that makes this integration possible.

📄 License

• Cập nhật sau

⭐ Don't forget to star this repo if it helped you!