n8n-nodes-zalo-gemazo

Community node n8n tích hợp Zalo theo hai luồng:

| Luồng | API | Dùng khi | |-------|-----|----------| | Zalo Bot (khuyến nghị doanh nghiệp) | Zalo Bot Platform — token chính thức | Chatbot, auto-reply, không cần tài khoản cá nhân | | Zalo cá nhân | zca-js — không chính thức | Tự động hóa tài khoản Zalo Web đầy đủ tính năng |

Cảnh báo (cá nhân): API không chính thức, mô phỏng Zalo Web. Có thể vi phạm điều khoản Zalo và dẫn đến khóa tài khoản. Nên dùng tài khoản phụ để thử nghiệm.

Cài đặt

Community Nodes (khuyến nghị)

1. Mở n8n → Settings → Community Nodes
2. Cài package: n8n-nodes-zalo-gemazo
3. Tải lại editor

Cài thủ công

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

Zalo Bot (API chính thức)

2 node Bot

| Node | Mô tả | |------|--------| | Zalo Bot Event Trigger | Nhận tin nhắn qua webhook (tự đăng ký khi activate) | | Zalo Bot Tương Tác | Gửi tin nhắn, ảnh, sticker |

Tạo bot và credential

1. Mở app Zalo → tìm OA Zalo Bot Manager → Tạo bot
2. Nhập tên bot (bắt đầu bằng Bot, ví dụ Bot MyShop)
3. Zalo gửi Bot Token dạng {bot_id}:{secret_key}
4. Trong n8n: credential Zalo Bot:
   • Bot Token: dán toàn bộ chuỗi token
   • Webhook Secret Token (tùy chọn): chỉ cần nếu cấu hình webhook thủ công trên Zalo Bot Manager

Hai cách cấu hình webhook

Cách A — n8n tự đăng ký (khuyến nghị)

1. Credential: chỉ điền Bot Token
2. Zalo Bot Event Trigger → bật Tự Đăng Ký Webhook
3. Activate workflow → n8n tự gọi setWebhook
4. Không cần điền Webhook trên Zalo Bot Manager

Cách B — cấu hình tay trên Zalo Bot Manager

1. Activate workflow trước → copy Production Webhook URL từ node trigger (dạng /webhook/..., không dùng /webhook-test/)
2. Trên Zalo Bot Manager: dán Webhook URL + Secret Token → Lưu thay đổi
3. Credential n8n: dán cùng Secret Token vào field Webhook Secret Token
4. Node trigger: tắt Tự Đăng Ký Webhook

HTTP được Zalo chấp nhận (http:// hoặc https://). Cần IP public + mở port (vd. 5678) để Zalo gọi được vào.

Workflow mẫu Bot

Zalo Bot Event Trigger (Text Message)
  → Zalo Bot Tương Tác (Send Message)
       chatId: {{ $json.message.chat.id }}
       text: Xin chào {{ $json.message.from.display_name }}!

Expression hữu ích:

| Expression | Mô tả | |------------|--------| | {{ $json.message.chat.id }} | Chat ID để trả lời | | {{ $json.message.text }} | Nội dung tin nhắn | | {{ $json.event_name }} | Loại sự kiện |

Yêu cầu và lưu ý Bot

• Webhook URL phải truy cập được từ internet (http hoặc https)
• Một bot chỉ gắn một webhook — workflow activate sau ghi đè workflow trước
• Secret Token trên Zalo phải trùng với credential n8n (hoặc để trống để n8n tự sinh)
• Cloudflare: Zalo gửi webhook với User-Agent: Java/1.8.0_192 — có thể bị chặn. Tạo rule WAF skip cho path chứa /webhook

Khắc phục “đã set nhưng không nhận tin”

| Nguyên nhân | Cách xử lý | |-------------|-----------| | Secret Token không khớp | Dán cùng secret vào credential Webhook Secret Token | | Dùng /webhook-test/ | Activate workflow, dùng URL /webhook/... (production) | | Port chưa mở | Mở firewall port n8n (vd. 5678) cho IP public | | Token cũ sau Reset | Cập nhật Bot Token mới vào credential n8n | | Cấu hình tay + tự đăng ký | Tắt Tự Đăng Ký Webhook nếu đã set trên Zalo |

Sắp có (Bot)

• getUpdates (polling, không cần HTTPS)
• sendChatAction (typing indicator)
• Quản lý webhook thủ công

Zalo cá nhân — 3 node chính

| Node | Mô tả | |------|--------| | Zalo Login QR | Đăng nhập QR, tự lưu credential | | Zalo Event Trigger | Lắng nghe tin nhắn, reaction, thu hồi, sự kiện nhóm | | Zalo Tương Tác | Gửi tin / quản lý bạn bè, nhóm, tài khoản, tool |

Zalo Tương Tác — Resource

| Resource | Ví dụ | |----------|--------| | Message | Gửi tin nhắn, sticker, voice (nhiều ảnh) | | Get | Bạn bè, nhóm, user info, sticker | | Friend | Kết bạn, chặn, alias, profile | | Group | Tạo/sửa nhóm, poll, ghi chú | | Account | Thông tin tài khoản, pin, test credential | | Tool | Xóa tin, reaction, typing, danh thiếp | | Custom API Call | Gọi method zca-js tùy ý |

Zalo Event Trigger — Listen Events

Chọn một hoặc nhiều: Message, Reaction, Undo, Group Event.

Output có field event (message, reaction, undo, group_event).

So sánh Bot vs Cá nhân

| | Zalo Bot | Zalo cá nhân | |---|----------|--------------| | API | Chính thức | Không chính thức | | Credential | Bot Token | Cookie + IMEI + UA | | Trigger | Webhook HTTPS | WebSocket | | Rủi ro khóa TK | Thấp | Cao | | Tính năng | Chat bot cơ bản | Đầy đủ (nhóm, poll, reaction…) |

Migration 0.10.0 — Portal khách hàng + Trial bắt buộc đăng nhập

• Trial: phải đăng ký/đăng nhập tại /portal trước khi kích hoạt (/portal/trial?installationId=...)
• Pro: mua qua /portal/buy — admin duyệt đơn (API thanh toán sẽ tích hợp sau)
• Quản lý license, xem key tại /portal
• POST /v1/trial public → 401 (dùng POST /api/customer/trial)
• Env ZALO_LICENSE_KEY* chỉ còn override nội bộ/dev

npm install [email protected]
# Deploy Worker + migration D1 0005 trước
# restart n8n

Portal: https://zalo-license-worker.hygge.workers.dev/portal/login

Migration 0.9.0 — License theo tài khoản Zalo/Bot

Phiên bản 0.9.0 gắn license/trial theo danh tính Zalo (cá nhân: zaloUserId, Bot: botId):

• Cùng credential Zalo/Bot dùng được trên mọi workflow và mọi thiết bị
• Trial Personal và Bot tách riêng — mỗi tài khoản trial 1 lần
• Đổi sang Zalo/Bot khác: trial mới (nếu chưa trial) hoặc reclaim key cũ
• Pro: rebind sang Zalo/Bot mới không giới hạn
• Static data: zaloLicense.personal và zaloLicense.bot (tự migrate từ format cũ)

npm install [email protected]
# restart n8n
# Deploy Worker + migration D1 0004 trước khi dùng

Env Pro (tùy chọn tách dòng):

ZALO_LICENSE_KEY_PERSONAL=ZLG-...
ZALO_LICENSE_KEY_BOT=ZLG-...
# hoặc ZALO_LICENSE_KEY cho cả hai

Migration 0.8.1 — Trial/license theo workflow

Phiên bản 0.8.1 sửa cách tính activation: 1 workflow = 1 license slot.

• Mọi node Zalo trong cùng workflow dùng chung installationId/instanceId
• Workflow thứ 2 được tính là slot mới và cần đăng ký trial/license riêng
• Tránh lỗi Đã vượt số instance cho phép khi dùng nhiều node trong cùng workflow

npm install [email protected]
# restart n8n

Migration 0.8.0 — Cache license 24h, tốc độ nhanh hơn

Phiên bản 0.8.0 tối ưu license check:

• Cache 24h trong workflow static data — lần chạy sau không gọi API (0ms network)
• Lần đầu: POST /v1/activate; lần sau (trong 24h): skip hoặc POST /v1/validate + JWT
• Bot webhook không check license mỗi tin — chỉ khi activate workflow
• Trang public không còn link Admin

npm install [email protected]
# restart n8n

Thu hồi key trên admin có hiệu lực chậm tối đa 24h. Khi có cache hợp lệ, node vẫn chạy nếu API tạm down.

Migration 0.7.3 — License không cần credential

Credential Zalo License đã gỡ hoàn toàn. License tự quản lý qua backend + workflow static data — không còn mục "Set up credential" trên node.

Trial

1. Chạy node Zalo lần đầu → mở link đăng ký từ lỗi
2. Điền form web → chạy lại node — license tự kích hoạt

Hướng dẫn: https://zalo-license-worker.hygge.workers.dev/register

Pro

Đặt biến môi trường trên n8n:

ZALO_LICENSE_KEY=ZLG-XXXXX-XXXXX

npm install [email protected]
# restart n8n

Migration 0.7.1 (Trial qua trang đăng ký web)

Phiên bản 0.7.1–0.7.2 yêu cầu đăng ký Trial trên web. (0.7.3 gỡ credential Zalo License.)

Migration 0.7.0 (superseded by 0.7.1)

Phiên bản 0.7.0 thay đổi cách nhận Trial: không dùng email (tránh spoof), trial được cấp tự động khi chạy Zalo Login QR lần đầu. (Luồng này đã thay bằng 0.7.1 — đăng ký web.)

Migration 0.6.0 (breaking — bắt buộc License Key)

Phiên bản 0.6.0 yêu cầu credential Zalo License trên cả 5 node. (Trial qua email đã thay bằng 0.7.0.)

Migration 0.5.0 (breaking change)

Phiên bản 0.5.x gộp toàn bộ node legacy vào 5 node public. Workflow cũ dùng node ẩn hoặc typeVersion cũ cần migrate thủ công.

Cài đặt trên VPS

npm install [email protected]
npm ls n8n-nodes-zalo-gemazo
# restart n8n (bắt buộc)
# Mở từng workflow → Update node → Save

Bảng thay node

| Node cũ (sẽ lỗi sau 0.5.0) | Thay bằng | |----------------------------|-----------| | zaloGroup | Zalo Tương Tác → Resource Group | | zaloUser / zaloAccount | Resource Get / Friend / Account | | zaloMessageTrigger | Zalo Event Trigger → Listen Message | | zaloReactionTrigger | Zalo Event Trigger → Listen Reaction | | zaloUndoTrigger | Zalo Event Trigger → Listen Undo | | zaloGroupEventTrigger | Zalo Event Trigger → Listen Group Event | | Zalo Tương Tác typeVersion 1–11 | Update node → v12, cấu hình lại Resource/Operation | | Zalo Event Trigger v1 | Update node → v2 | | Zalo Bot nodes v1 | Update node → v2 |

Version mới

| Node | Version | |------|---------| | Zalo Tương Tác | 12 only | | Zalo Event Trigger | 2 only | | Zalo Login QR | 1 | | Zalo Bot Tương Tác | 2 only | | Zalo Bot Event Trigger | 2 only |

Chuyển từ node cũ (trước 0.5.0)

| Node cũ | Thay bằng | |---------|-----------| | Zalo Message | Zalo Tương Tác → Resource Message | | Zalo User | Resource Friend / Get | | Zalo Group | Resource Group | | Zalo Account | Resource Account | | Zalo Sticker | Resource Get | | Zalo Poll / Note | Resource Group | | Zalo Message Trigger | Zalo Event Trigger → Message | | Zalo Reaction Trigger | Zalo Event Trigger → Reaction | | Zalo Undo Trigger | Zalo Event Trigger → Undo | | Zalo Group Event Trigger | Zalo Event Trigger → Group Event |

Sau 0.5.0, node legacy không còn trong package — workflow chưa migrate sẽ hiện "unknown node".

Credential zaloApi (cá nhân)

| Field | Mô tả | |-------|--------| | Cookie | JSON cookie từ Zalo Web hoặc Zalo Login QR | | IMEI | localStorage.getItem('z_uuid') trên chat.zalo.me | | User Agent | navigator.userAgent từ trình duyệt | | Proxy | Tùy chọn |

Workflow mẫu (cá nhân)

1. Zalo Login QR → quét QR → credential Zalo - Tên (SĐT)
2. Zalo Event Trigger → Listen Message → test event
3. Zalo Tương Tác → Resource Message → Gửi tin nhắn
   • User/Group Id: ={{ $json.threadId }}
   • Attachments: ={{ $json.imageUrls.join(",") }} (album)

Phát triển

npm install
npm run build
npm run lint

License

MIT — xem LICENSE.