n8n-nodes-tran-minh-long-zalo

Bộ community node Zalo tiếng Việt cho n8n, dùng Zalo Web session qua cookie,
IMEI và userAgent. Package này được tối ưu cho workflow báo cáo công trình,
gửi tin nhắn kèm nhiều ảnh, video, mention từng người và mention @All.

Cài đặt

Trong n8n, vào Settings → Community nodes → Install và nhập:

n8n-nodes-tran-minh-long-zalo

Sau khi cài xong, tạo credential Zalo API Credentials gồm:

• cookie: cookie JSON lấy từ Zalo Web.
• imei: IMEI của phiên Zalo Web.
• userAgent: userAgent cùng phiên đăng nhập.
• proxy: tùy chọn, chỉ dùng khi hạ tầng của bạn cần proxy.

Node có trong package

• Zalo Message Trigger: lắng nghe tin nhắn cá nhân/nhóm, chuẩn hóa text, ảnh,
  sender, group, event id để dùng trong workflow.
• Zalo Send Message: gửi text, ảnh, video, text kèm ảnh, mention từng người,
  mention @All, ảnh URL, ảnh binary, base64 và local path.
• Zalo Health Check: kiểm tra session còn đăng nhập được không, cảnh báo cookie
  hết hạn hoặc sắp hết hạn.
• Zalo Login Via QR Code: tạo QR để refresh credential khi Zalo bắt đăng nhập lại.
• Zalo Group: lấy thông tin nhóm, tìm group id.
• Zalo User: lấy thông tin user, tìm UID để mention hoặc gửi tin nhắn cá nhân.

Tính năng chính

• Gửi nhiều ảnh không giới hạn tổng số ảnh. Node tự chia batch theo Image Batch Size
  và nghỉ giữa batch theo Image Batch Delay MS.
• Hỗ trợ ảnh từ URL, chuỗi URL ngăn bởi dấu |, mỗi URL một dòng, fixed collection,
  JSON array, binary n8n, base64 data URL và local file path.
• Tự tải ảnh Zalo photo-stal-*.zdn.vn bằng cookie/userAgent trong credential,
  kèm header Referer phù hợp để giảm lỗi 403 khi gửi lại ảnh lấy từ Zalo.
• Không bao giờ gọi Zalo với file path null. Nếu ảnh lỗi, node trả mã lỗi rõ
  như ZALO_IMAGE_DOWNLOAD_FAILED, ZALO_IMAGE_UNSUPPORTED_MIME,
  ZALO_IMAGE_PATH_INVALID.
• Khi workflow bật Continue On Fail, output vẫn có success=false,
  error_code, error_details, cookie_status để dễ debug execution.
• Mention hỗ trợ:
  • UID đơn.
  • Danh sách UID.
  • JSON object có uid, name, label, pos, len.
  • all, @all, -1 để mention @All.
  • Tự thêm label @Tên hoặc @All vào nội dung nếu thiếu, giúp Zalo nhận đúng
    pos và len.
• Gửi video bằng URL public, kèm thumbnail URL và duration nếu có.

Ví dụ gửi báo cáo kèm ảnh

Message:

Kính gửi: @All @Quản lý 1 @Quản lý 2

BÁO CÁO NGÀY: 01/01/2026
...
Em xin gửi hình ảnh đính kèm theo tin này.

Image URLs có thể là:

https://example.com/images/site-photo-01.jpg
https://example.com/images/site-photo-02.jpg

Hoặc truyền từ JSON:

{
  "imageUrls": [
    "https://example.com/images/site-photo-01.jpg",
    "https://example.com/images/site-photo-02.jpg"
  ],
  "zaloMentions": [
    { "uid": "-1", "name": "All" },
    { "uid": "1000000000000000001", "name": "Quản lý 1" },
    { "uid": "1000000000000000002", "name": "Quản lý 2" }
  ]
}

Lưu ý vận hành

Package dùng API Zalo Web không chính thức thông qua zca-js. Nếu Zalo bắt
CAPTCHA, xác minh bảo mật, đăng nhập lại hoặc chặn session trùng, bạn vẫn cần
quét QR để refresh credential. Node sẽ báo lỗi rõ ràng thay vì âm thầm bỏ qua.

Không commit cookie, IMEI, userAgent hoặc npm token vào git. Hãy lưu credential
trong n8n hoặc secret manager của hạ tầng.

Cập nhật 1.1.8

• Zalo Send Message có thêm tuỳ chọn Skip Failed Images, mặc định bật.
• Khi gửi nhiều ảnh, nếu một số URL Zalo hết hạn, bị 404, 403 hoặc không đọc được,
  node vẫn gửi các ảnh hợp lệ còn lại.
• Output trả thêm skipped_image_count và skipped_images để xem ảnh nào bị bỏ qua.
• Nếu tất cả ảnh được yêu cầu đều lỗi, node trả ZALO_IMAGE_ALL_FAILED để workflow
  giữ dữ liệu retry thay vì gửi thiếu toàn bộ ảnh.
• Mentions được sắp xếp theo pos tăng dần trước khi gửi sang Zalo. Điều này giúp
  @All hoạt động ổn định hơn khi workflow truyền danh sách mention không đúng thứ tự.