zalo-toluck

Node n8n tương tác Zalo Cá Nhân: Webhook nhận tin nhắn, gửi tin nhắn Nhóm theo ID hoặc Cá nhân theo ID / Số điện thoại

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)

n8n community node
License: MIT

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:

  1. 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).
  2. 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.
  3. Send to User: Gửi tin nhắn trực tiếp tới Cá nhân bằng userId hoặc Số điện thoại.
  4. 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).
  • 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)

  1. Đăng nhập vào n8n của bạn.
  2. Vào Settings -> Community Nodes.
  3. Bấm Install a community node.
  4. Nhập tên package:
    n8n-nodes-zalo-toluck
    
    (hoặc URL repo: https://github.com/hungtrankanet/zalo-node-toluck.git)
  5. Đá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)

  1. Trong n8n, chọn Credentials -> New Credential -> tìm Zalo Personal API.
  2. Điền các tham số:
    • Zalo Agent Base URL: Địa chỉ máy chủ Zalo Agent (ví dụ: http://zalo-agent:3032 hoặc https://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).

🔄 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:

  1. Zalo Personal Trigger nhận tin nhắn đến.
  2. Switch Node phân luồng:
    • Nếu là tin nhắn Nhóm (isGroup == true) ➡️ Kích hoạt Zalo Personal: Send to Group.
    • Nếu là tin nhắn Cá nhân (isGroup == false) ➡️ Kích hoạt Zalo Personal: Send to User.
  3. 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.

Discussion