n8n-nodes-zalo-gemazo

Community node n8n tích hợp Zalo theo hai luồ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

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:

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”

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

Zalo Tương Tác — Resource

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

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 n8n-nodes-zalo-gemazo@0.10.0
# 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 n8n-nodes-zalo-gemazo@0.9.0
# 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 n8n-nodes-zalo-gemazo@0.8.1
# 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 n8n-nodes-zalo-gemazo@0.8.0
# 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 n8n-nodes-zalo-gemazo@0.7.3
# 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 n8n-nodes-zalo-gemazo@0.5.2
npm ls n8n-nodes-zalo-gemazo
# restart n8n (bắt buộc)
# Mở từng workflow → Update node → Save

Bảng thay node

Version mới

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

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)

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.