Package Information
Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 1.0.0
Author: TOLUCK SAAS Team
Documentation
n8n-nodes-zalo-toluck (TOLUCK Zalo Personal Node)
Package Node chuyên biệt dành cho n8n để tự động hóa tương tác qua Tài Khoản Zalo Cá Nhân:
- Webhook Inbound Trigger: Bắt sự kiện tin nhắn đến theo thời gian thực (Cả chat riêng 1-1 và tin nhắn trong Nhóm Zalo).
- Send to Group: Gửi tin nhắn trực tiếp vào một Nhóm Zalo bất kỳ bằng
groupId. - Send to User: Gửi tin nhắn trực tiếp tới Cá nhân bằng
userIdhoặcSố điện thoại. - Group & Contact Operations: Lấy danh sách nhóm chat, tra cứu thông tin Zalo qua số điện thoại, gửi kết bạn tự động.
🌟 1. Tính Năng Chính
⚡ Node Kích Hoạt: Zalo Personal Trigger
- Nhận tin nhắn cá nhân (1-1 Chat): Nhận tin nhắn riêng tư từ khách hàng, bóc tách
senderId,senderName,message,timestamp. - Nhận tin nhắn nhóm (Group Chat): Bắt sự kiện khi có tin nhắn trong nhóm Zalo, bóc tách
groupId,senderId,senderName,message. - Bộ lọc thông minh (Filter Scope):
- Nhận tất cả tin nhắn (Cá nhân & Nhóm).
- Chỉ nhận tin nhắn cá nhân.
- Chỉ nhận tin nhắn trong nhóm.
- Lọc theo Group ID: Chỉ kích hoạt workflow với các nhóm Zalo quan trọng chỉ định.
- Chống lặp tin nhắn Bot (Ignore Self Messages): Tự động loại trừ tin nhắn do chính bot gửi ra để tránh vòng lặp phản hồi vô tận.
🚀 Node Hành Động: Zalo Personal
- Gửi tin nhắn Nhóm (Send to Group): Gửi tin nhắn văn bản vào Nhóm Zalo qua
groupId. - Gửi tin nhắn Cá nhân (Send to User):
- Gửi bằng
Zalo User ID. - Gửi bằng
Số điện thoại(tự động phân giải sang User ID và gửi tin).
- Gửi bằng
- Tra cứu người dùng (Find User by Phone): Tìm kiếm tên, ID, avatar Zalo từ số điện thoại.
- Lấy danh sách nhóm (Get All Groups): Trả về danh sách tất cả các nhóm Zalo tài khoản đang tham gia.
- Gửi lời mời kết bạn (Send Friend Request): Gửi kết bạn kèm lời chào cá nhân hóa.
📦 2. Hướng Dẫn Cài Đặt Vào n8n
Cách 1: Cài đặt qua Giao diện n8n (Community Nodes)
- Đăng nhập vào n8n của bạn.
- Vào Settings -> Community Nodes.
- Bấm Install a community node.
- Nhập tên package:
(hoặc URL repo:n8n-nodes-zalo-toluckhttps://github.com/hungtrankanet/zalo-node-toluck.git) - Đánh dấu đồng ý điều khoản rủi ro và bấm Install.
Cách 2: Cài đặt trực tiếp trong Container n8n (Khuyên dùng cho Self-Hosted)
Nếu bạn chạy n8n trên Docker, mở terminal máy chủ và chạy:
docker exec -it toluck-n8n npm install https://github.com/hungtrankanet/zalo-node-toluck.git
docker restart toluck-n8n
Cách 3: Mount qua Docker Compose
Thêm volume mount vào file docker-compose.yml của n8n:
services:
n8n:
image: n8nio/n8n:latest
volumes:
- /path/to/zalo-node-toluck/dist:/home/node/.n8n/custom/node_modules/n8n-nodes-zalo-personal/dist:ro
- /path/to/zalo-node-toluck/package.json:/home/node/.n8n/custom/node_modules/n8n-nodes-zalo-personal/package.json:ro
🔑 3. Cấu Hình Thông Tin Xác Thực (Credentials)
- Trong n8n, chọn Credentials -> New Credential -> tìm Zalo Personal API.
- Điền các tham số:
- Zalo Agent Base URL: Địa chỉ máy chủ Zalo Agent (ví dụ:
http://zalo-agent:3032hoặchttps://app.toluck.com.vn:3032). - Account ID: ID tài khoản Zalo cá nhân trong hệ thống (mặc định:
1). - API Secret Key: Khóa bảo mật nếu có bật xác thực (tùy chọn).
- Zalo Agent Base URL: Địa chỉ máy chủ Zalo Agent (ví dụ:
🔄 4. Mẫu Kịch Bản n8n (Workflow Template)
Repository cung cấp sẵn file workflow mẫu tại:
📂 workflows/zalo-personal-ai-auto-reply.json
Luồng hoạt động:
Zalo Personal Triggernhận tin nhắn đến.Switch Nodephân luồng:- Nếu là tin nhắn Nhóm (
isGroup == true) ➡️ Kích hoạtZalo Personal: Send to Group. - Nếu là tin nhắn Cá nhân (
isGroup == false) ➡️ Kích hoạtZalo Personal: Send to User.
- Nếu là tin nhắn Nhóm (
- Bạn có thể chèn các node AI (OpenAI, Anthropic Claude, LangChain Agent) ở giữa để tự động trả lời tư vấn khách hàng 24/7.
🛡️ 5. Chuẩn Kiến Trúc & Chịu Tải
- Chịu tải cao: Kiến trúc tách rời hoàn toàn với core SaaS, hoạt động dạng microservice bất đồng bộ qua WebSocket listener.
- Tuân thủ quy chuẩn: Mọi tệp code đều được kiểm soát nghiêm ngặt $\le 500$ dòng code (
RULE[user_global]). - Bảo mật: Không lưu trữ mật khẩu, session được mã hóa qua cơ chế cookie/token bảo mật.
📄 6. Giấy Phép (License)
Phát hành theo giấy phép MIT. Bản quyền thuộc về TOLUCK SaaS Team.