n8n-nodes-livo-zalo

Bộ node n8n cho tích hợp Zalo Messaging thông qua Livo Zalo API Service. Node này cho phép bạn tự động hóa các tác vụ Zalo trong n8n workflow của bạn.

Tính năng

• Đa tài khoản: Quản lý nhiều tài khoản Zalo cùng lúc
• Real-time: Nhận tin nhắn và sự kiện bạn bè theo thời gian thực qua SignalR
• Bảo mật: Dữ liệu được xử lý hoàn toàn trong hệ thống của bạn
• Dễ sử dụng: Tích hợp đơn giản với n8n workflow

Yêu cầu

• n8n phiên bản 1.60.0 trở lên
• Node.js 18.10 trở lên
• Livo Zalo API Service đang chạy (xem phần Setup Backend)

Cài đặt

Cài đặt từ npm

cd ~/.n8n/nodes
npm install n8n-nodes-livo-zalo

Sau đó khởi động lại n8n:

n8n start

Cài đặt từ source

cd ~/.n8n/nodes
git clone https://github.com/tct68/zalo-node.git n8n-nodes-livo-zalo
cd n8n-nodes-livo-zalo
npm install
npm run build

Setup Backend

Node này yêu cầu Livo Zalo API Service để hoạt động. Đây là một service FastAPI cung cấp:

1. Zalo Node Service (Port 7616): Xử lý đăng nhập, quản lý session, gửi tin nhắn
2. ZaloUser Service (Port 7615): SignalR Hub để stream real-time events

Khởi động Services

# 1. Khởi động Zalo Node Service
cd corepos/services/zalonode
npm start  # Default port 7616

# 2. Khởi động ZaloUser Service (.NET)
cd corepos/services/zalouser
dotnet run  # Default port 7615

Xem thêm chi tiết trong file CLAUDE.md của project.

Credential Configuration

Khi sử dụng các node Livo Zalo, bạn cần cấu hình credential:

1. API Key: API key được cấp bởi Zalo Node Service
2. Base URL: URL của Zalo Node Service (mặc định: http://localhost:7616)

Node sẽ tự động kết nối đến SignalR Hub tại {baseUrl}/zalouser/signalr-hubs/zalo.

Available Nodes

1. Zalo Login By QR

Đăng nhập tài khoản Zalo qua mã QR.

Parameters:

• tenantId: ID định danh cho tài khoản (bắt buộc)

Output:

• QR code để quét
• Thông tin tài khoản sau khi đăng nhập thành công

2. Zalo Send Message

Gửi tin nhắn văn bản đến người dùng hoặc nhóm.

Operations:

• Send text message
• Send message to group
• Send message to user

Parameters:

• threadId: ID của cuộc trò chuyện hoặc nhóm
• message: Nội dung tin nhắn

3. Zalo User

Quản lý người dùng và bạn bè Zalo.

Operations:

• acceptFriendRequest: Chấp nhận lời mời kết bạn
• sendFriendRequest: Gửi lời mời kết bạn
• blockUser: Chặn người dùng
• unblockUser: Bỏ chặn người dùng
• changeAccountAvatar: Đổi ảnh đại diện
• getUserInfo: Lấy thông tin người dùng
• getAllFriends: Lấy danh sách bạn bè
• findUser: Tìm kiếm người dùng qua số điện thoại

4. Zalo Group

Quản lý nhóm Zalo.

Operations:

• createGroup: Tạo nhóm mới
• getGroupInfo: Lấy thông tin nhóm
• addGroupDeputy: Thêm phó nhóm
• addUserToGroup: Thêm thành viên
• changeGroupAvatar: Đổi avatar nhóm
• changeGroupName: Đổi tên nhóm
• getGroupMembers: Lấy danh sách thành viên
• getAllGroups: Lấy tất cả nhóm
• removeUserFromGroup: Xóa thành viên

5. Zalo Message Trigger

Node trigger lắng nghe tin nhắn Zalo real-time qua SignalR.

Parameters:

• selfListen: Có lắng nghe tin nhắn từ chính mình không (mặc định: false)

Output:

• Tin nhắn nhận được với đầy đủ thông tin (người gửi, nội dung, thời gian,...)

Cách hoạt động:

• Kết nối đến SignalR Hub tại ZaloUser Service
• Tự động reconnect khi mất kết nối
• Stream tin nhắn theo thời gian thực

6. Zalo Friend Trigger

Node trigger lắng nghe sự kiện bạn bè (friend request, accept, etc.) qua SignalR.

Output:

• Sự kiện bạn bè với thông tin chi tiết (userId, displayName, avatar,...)

Event Types:

• friend_request: Có lời mời kết bạn mới
• friend_accept: Lời mời kết bạn được chấp nhận
• Các event khác từ Zalo

7. Zalo Poll

Quản lý poll/bình chọn trong nhóm Zalo.

8. Zalo Tag

Quản lý tag cho liên hệ Zalo.

9. Zalo ZNS

Gửi tin nhắn ZNS (Zalo Notification Service).

10. Zalo ZNS Webhook

Nhận webhook từ ZNS.

Ví dụ Workflow

Workflow 1: Auto Reply

Zalo Message Trigger → Check Message Content → Send Reply

1. Kéo node Zalo Message Trigger vào canvas
2. Cấu hình credential (API Key + Base URL)
3. Thêm node IF để kiểm tra nội dung tin nhắn
4. Thêm node Zalo Send Message để trả lời

Workflow 2: Friend Request Auto Accept

Zalo Friend Trigger → Check Event Type → Accept Friend Request

1. Kéo node Zalo Friend Trigger vào canvas
2. Thêm node IF để kiểm tra event type = 'friend_request'
3. Thêm node Zalo User (operation: acceptFriendRequest)

Architecture

Real-time Communication Flow

Zalo → ZaloNode (7616) → Webhooks → ZaloUser Service (7615)
                                            ↓
                                      SignalR Hub
                                            ↓
                                    n8n Trigger Nodes
                                            ↓
                                    Your Workflow

1. ZaloNode Service lắng nghe events từ Zalo (qua zca-js SDK)
2. Push events qua webhook đến ZaloUser Service
3. ZaloUser Service broadcast events qua SignalR Hub
4. n8n Trigger Nodes subscribe và nhận events real-time
5. Trigger workflow của bạn

Multi-tenant Support

Mỗi tài khoản Zalo được xác định bởi tenantId. SignalR Hub tự động tạo group cho mỗi tenant, đảm bảo tin nhắn chỉ được gửi đến đúng tài khoản.

Troubleshooting

Node không nhận được tin nhắn

1. Kiểm tra Zalo Node Service đang chạy: http://localhost:7616/docs
2. Kiểm tra ZaloUser Service đang chạy: http://localhost:7615
3. Kiểm tra credential (API Key, Base URL)
4. Xem log của n8n: n8n start --tunnel

Lỗi kết nối SignalR

• Đảm bảo ZaloUser Service đang chạy
• Kiểm tra Base URL trong credential
• Hub URL phải là: {baseUrl}/zalouser/signalr-hubs/zalo

Tin nhắn bị delay

• SignalR sử dụng WebSocket, nên tin nhắn là real-time
• Nếu bị delay, kiểm tra network connection
• Xem log của ZaloUser Service

Development

Build từ source

npm install
npm run build

Watch mode (development)

npm run dev

Lint & Format

npm run lint
npm run format

Tech Stack

• n8n-workflow: n8n workflow SDK
• SignalR: Real-time communication (@microsoft/signalr)
• Axios: HTTP client
• livo-zca-js: Zalo SDK wrapper
• TypeScript: Type-safe development

Lưu ý quan trọng

⚠️ Cảnh báo: 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à có thể khiến 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. Hãy cân nhắc trước khi sử dụng.

Credits

• Dựa trên zca-js library
• SignalR integration by Livo Team

License

MIT

Author

Thuong Truong

• Email: [email protected]
• GitHub: https://github.com/tct68

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

Nếu gặp vấn đề hoặc có câu hỏi, vui lòng:

1. Mở issue trên GitHub: https://github.com/tct68/zalo-node/issues
2. Email: [email protected]