n8n-nodes-zalo-oa-enterprise

Package n8n custom nodes để tích hợp với Zalo Official Account (OA) API. Package này cung cấp các nodes để nhận webhook events từ Zalo OA và gửi tin nhắn đến người dùng.

✨ Tính năng

🔔 Zalo OA Trigger Node

• Webhook Trigger nhận events từ Zalo Official Account
• 6 Output Ports để route các loại events khác nhau:
  • Port 0: Tin nhắn văn bản (user_send_text)
  • Port 1: Hình ảnh (user_send_image, user_send_gif)
  • Port 2: Sticker (user_send_sticker)
  • Port 3: Vị trí (user_send_location)
  • Port 4: Tương tác/Theo dõi (user_follow, user_unfollow, user_click_button, user_click_link, v.v.)
  • Port 5: Các events khác (fallback)
• Webhook Signature Verification (HMAC-SHA256) để bảo mật
• Challenge Verification tự động cho Zalo webhook setup
• Idempotency Support - chống xử lý trùng tin nhắn

📤 Zalo OA Action Node

• Gửi tin nhắn văn bản (sendText)
• Gửi hình ảnh từ URL hoặc binary data (sendImage)
• Gửi sticker (sendSticker)
• Lấy thông tin người dùng (requestUserInfo)

🔐 OAuth2 Authentication

• Tích hợp OAuth2 với Zalo OA API
• Tự động quản lý token refresh (one-time refresh token handling)
• Hỗ trợ App ID và App Secret từ Zalo Developer Console

🛡️ Reliability Features

• Exponential Backoff Retry cho rate limits (HTTP 429)
• Automatic Token Refresh khi token hết hạn
• Error Handling với thông báo lỗi rõ ràng từ Zalo API
• Type-safe với TypeScript interfaces

📦 Cài đặt

Yêu cầu

• n8n version 1.0.0 trở lên
• Node.js 18.10.0 trở lên

Cài đặt qua npm

npm install n8n-nodes-zalo-oa-enterprise

Cài đặt trong n8n

1. Mở n8n và vào Settings → Community Nodes
2. Click Install a community node
3. Nhập package name: n8n-nodes-zalo-oa-enterprise
4. Click Install
5. Restart n8n nếu cần

Cài đặt thủ công (n8n self-hosted)

Nếu bạn đang chạy n8n self-hosted, bạn có thể cài đặt package vào thư mục custom nodes:

cd ~/.n8n/custom
npm install n8n-nodes-zalo-oa-enterprise

Sau đó restart n8n.

⚙️ Cấu hình

Bước 1: Tạo Zalo Application

1. Truy cập Zalo Developers
2. Đăng nhập và tạo ứng dụng mới
3. Lấy App ID và App Secret từ Zalo Developer Console
4. Cấu hình Redirect URI (ví dụ: https://your-n8n-instance.com/rest/oauth2-credential/callback)

Bước 2: Tạo Credentials trong n8n

Version 1.0.9+ sử dụng Custom OAuth Flow (không còn phụ thuộc vào n8n's standard OAuth2Api):

Option A: OAuth Flow (Recommended)

1. Trong n8n, tạo Credential mới
2. Chọn Zalo Official Account API
3. Chọn Authentication Method: "OAuth Flow (Recommended)"
4. Nhập thông tin:
   • App ID: App ID từ Zalo Developer Console
   • App Secret: App Secret từ Zalo Developer Console
   • Redirect URI: https://your-n8n-instance.com/rest/oauth2-credential/callback
     • ⚠️ Phải match chính xác với Redirect URI trong Zalo Developer Console
5. Generate Authorization URL:
   • Format: https://oauth.zaloapp.com/v4/oa/permission?app_id={APP_ID}&redirect_uri={REDIRECT_URI}
   • Thay {APP_ID} bằng App ID của bạn
   • Thay {REDIRECT_URI} bằng URL-encoded Redirect URI
   • Hoặc sử dụng helper script: node scripts/zalo-oauth-helper.js generate <appId> <redirectUri>
6. Authorize Application:
   • Copy và mở Authorization URL trong browser mới
   • Đăng nhập Zalo và authorize
   • Copy authorization code từ callback URL (parameter code)
7. Exchange Code for Tokens:
   • Paste authorization code vào field "Authorization Code"
   • Sử dụng helper script hoặc HTTP Request node để exchange:

     node scripts/zalo-oauth-helper.js exchange <appId> <appSecret> <authCode>

   • Paste Access Token và Refresh Token vào credential (chọn "Manual Token Input")
8. Click Test và lưu credentials

Option B: Manual Token Input

1. Chọn Authentication Method: "Manual Token Input"
2. Nhập:
   • Access Token: Access Token từ Zalo
   • Refresh Token: Refresh Token từ Zalo
   • Token Expiry: (Optional) Thời gian hết hạn token
3. Click Test và lưu credentials

📖 Chi tiết: Xem ZALO_OA_AUTH_HELPER.md để biết thêm hướng dẫn chi tiết.

Bước 3: Cấu hình Webhook (cho Trigger Node)

1. Trong Zalo Developer Console, vào phần Webhook
2. Nhập Callback URL: URL của n8n webhook endpoint
   • Ví dụ: https://your-n8n-instance.com/webhook/zalo-oa
3. Kích hoạt các events cần thiết
4. Zalo sẽ gửi challenge request để verify webhook
5. Trigger node sẽ tự động xử lý challenge verification

🚀 Sử dụng

Ví dụ 1: Webhook Trigger - Nhận tin nhắn văn bản

1. Thêm node Zalo OA Trigger vào workflow
2. Kết nối credentials đã tạo
3. Bật Verify Signature (khuyến nghị)
4. Kết nối output port Text Message (Port 0) với node xử lý tiếp theo
5. Khi người dùng gửi tin nhắn văn bản, workflow sẽ được trigger

Output data structure:

{
  "event": "user_send_text",
  "timestamp": 1234567890,
  "sender": {
    "id": "user_id",
    "user_id_by_app": "user_id_by_app"
  },
  "message": {
    "text": "Nội dung tin nhắn"
  }
}

Ví dụ 2: Gửi tin nhắn văn bản

1. Thêm node Zalo OA vào workflow
2. Chọn Resource: Message
3. Chọn Operation: Send Text
4. Nhập User ID: user_id_by_app của người nhận
5. Nhập Message Text: Nội dung tin nhắn
6. Kết nối credentials
7. Execute workflow

Ví dụ 3: Gửi hình ảnh từ URL

1. Thêm node Zalo OA vào workflow
2. Chọn Resource: Message
3. Chọn Operation: Send Image
4. Chọn Image Source: URL
5. Nhập Image URL: URL của hình ảnh
6. Nhập User ID: user_id_by_app của người nhận
7. Execute workflow

Ví dụ 4: Gửi hình ảnh từ Binary Data

1. Thêm node để lấy hình ảnh (ví dụ: HTTP Request, Read Binary File)
2. Thêm node Zalo OA
3. Chọn Resource: Message
4. Chọn Operation: Send Image
5. Chọn Image Source: Binary Data
6. Chọn Binary Property: Tên property chứa binary data (mặc định: data)
7. Lưu ý: Zalo OA chỉ hỗ trợ định dạng JPG và PNG
8. Execute workflow

Ví dụ 5: Gửi Sticker

1. Thêm node Zalo OA
2. Chọn Resource: Message
3. Chọn Operation: Send Sticker
4. Nhập Sticker ID: ID của sticker (ví dụ: 123456)
5. Nhập User ID: user_id_by_app của người nhận
6. Execute workflow

Ví dụ 6: Lấy thông tin người dùng

1. Thêm node Zalo OA
2. Chọn Resource: User
3. Chọn Operation: Request User Info
4. Nhập User ID: user_id_by_app của người dùng
5. Execute workflow

Output data structure:

{
  "error": 0,
  "data": {
    "user_id": "user_id",
    "user_id_by_app": "user_id_by_app",
    "display_name": "Tên người dùng",
    "avatar": "https://..."
  }
}

📚 API Reference

Zalo OA Trigger Node

Parameters

• Verify Signature (boolean, default: true): Xác thực webhook signature từ Zalo

Output Ports

• Port 0 - Text Message: Tin nhắn văn bản
• Port 1 - Image: Hình ảnh và GIF
• Port 2 - Sticker: Sticker
• Port 3 - Location: Vị trí
• Port 4 - Interactive/Follow: Các events tương tác và theo dõi
• Port 5 - Others/Fallback: Các events khác

Supported Events

• user_send_text → Port 0
• user_send_image, user_send_gif → Port 1
• user_send_sticker → Port 2
• user_send_location → Port 3
• user_follow, user_unfollow, user_click_button, user_click_link, user_click_oa, user_view_oa, user_block, user_unblock → Port 4
• Tất cả events khác → Port 5

Zalo OA Action Node

Resources và Operations

Message Resource:

• sendText: Gửi tin nhắn văn bản
  • Parameters: userId, messageText
• sendImage: Gửi hình ảnh
  • Parameters: userId, imageSource (url/binary), imageUrl hoặc binaryProperty
• sendSticker: Gửi sticker
  • Parameters: userId, stickerId

User Resource:

• requestUserInfo: Lấy thông tin người dùng
  • Parameters: userId

🔧 Troubleshooting

Lỗi: "No access token found"

Nguyên nhân: Credentials chưa được authenticate hoặc OAuth2 flow chưa hoàn tất.

Giải pháp:

1. Kiểm tra credentials đã được kết nối chưa
2. Click Connect my account trong credentials để hoàn tất OAuth2 flow
3. Đảm bảo App ID và App Secret đúng

Lỗi: "Invalid webhook signature"

Nguyên nhân: Signature verification thất bại.

Giải pháp:

1. Kiểm tra App Secret trong credentials có đúng không
2. Đảm bảo webhook endpoint nhận được raw body (không bị parse JSON trước khi verify)
3. Tạm thời tắt signature verification nếu cần debug (không khuyến nghị cho production)

Lỗi: "Zalo OA chỉ hỗ trợ định dạng JPG và PNG"

Nguyên nhân: Hình ảnh không phải JPG hoặc PNG.

Giải pháp:

1. Chuyển đổi hình ảnh sang JPG hoặc PNG trước khi gửi
2. Sử dụng node Convert Image trong n8n để convert format

Lỗi: HTTP 429 (Rate Limit)

Nguyên nhân: Vượt quá rate limit của Zalo API.

Giải pháp:

• Package tự động retry với exponential backoff (1s → 2s → 4s → 8s)
• Nếu vẫn lỗi, đợi một lúc rồi thử lại
• Kiểm tra rate limits trong Zalo Developer Console

Webhook không nhận được events

Nguyên nhân: Webhook chưa được cấu hình đúng.

Giải pháp:

1. Kiểm tra webhook URL trong Zalo Developer Console
2. Đảm bảo n8n instance có thể nhận requests từ internet (public URL)
3. Kiểm tra firewall và security groups
4. Xem logs của n8n để debug

🔒 Security

• OAuth2 Authentication: Tất cả API calls đều yêu cầu OAuth2 token
• Webhook Signature Verification: Verify HMAC-SHA256 signature từ Zalo (khuyến nghị bật)
• Token Management: n8n tự động quản lý token refresh, tránh race conditions
• Error Messages: Không expose sensitive information (tokens, secrets) trong error messages

📝 License

MIT License - Xem file LICENSE để biết thêm chi tiết.

🤝 Đóng góp

Contributions are welcome! Vui lòng tạo issue hoặc pull request trên GitHub.

📞 Hỗ trợ

• GitHub Issues: https://github.com/pmtuan0206/n8n-nodes-zalo-oa-enterprise/issues
• Zalo Developer Documentation: https://developers.zalo.me/docs/official-account

🙏 Acknowledgments

• n8n - Workflow automation platform
• Zalo Developers - Zalo Official Account API

Made with ❤️ for the n8n community