Description
@bautran1911/n8n-nodes-zalo-oa
n8n community node tích hợp Zalo Official Account (Zalo OA) vào workflow n8n — hỗ trợ Webhook Trigger nhận tin nhắn từ người dùng, gửi tin tư vấn (CS Message) để tự động phản hồi chatbot AI, gửi ZBS Template Message qua số điện thoại và tự động quản lý Access Token.
—
Mục lục
- Giới thiệu
- Cài đặt
- Cấu hình Credential
- Lấy Access Token và Refresh Token từ Zalo
- Zalo OA Trigger (Webhook)
- Workflow chatbot AI với Zalo OA
- Operations
- Ví dụ sử dụng
- Compatibility
- Tài nguyên
- Tác giả
- ☕ Ủng hộ tác giả
- ⚡ Webhook Trigger: Nhận realtime các sự kiện
usersendtext/image/link/audio/video/sticker/location/file/gif,follow,unfollow,usersubmitinfo,userseenmessage,… Có xác thực chữ kýX-ZEvent-Signaturevà lọc event theo ý. - 💬 Gửi Tin Tư Vấn (CS Message): Gửi tin nhắn văn bản hoặc ảnh đính kèm (URL hoặc Attachment ID) tới user đã tương tác với OA trong vòng 7 ngày (dùng cho chatbot AI phản hồi).
- 📨 ZBS Template Message: Gửi tin mẫu đã duyệt qua số điện thoại.
- 👤 Quản lý Người Dùng: Truy xuất danh sách người quan tâm, chi tiết người dùng.
- 💭 Quản lý Hội Thoại: Đọc lịch sử tin nhắn đã trao đổi với khách hàng.
- 🏢 Thông Tin OA: Lấy profile Zalo Official Account.
- 🔄 Refresh Access Token qua hành động Resource Token và ghi đè vào n8n credential (khi đã cấu hình n8n API).
– Cách 2: API Explorer (Khuyên dùng)
– Cách 1: OAuth v4 (Tích hợp hệ thống)
—
Giới thiệu
Zalo OA là Trang Zalo Official Account — nền tảng nhắn tin của Zalo dành cho doanh nghiệp. Package này cung cấp 2 node:
1. Zalo OA (action node) — gọi các API của Zalo OpenAPI / Zalo Business Solution (ZBS).
2. Zalo OA Trigger (webhook trigger) — nhận sự kiện webhook từ Zalo OA để khởi động workflow (chatbot AI, auto-reply, phân loại tin nhắn…).
Tính năng chính:
—
Cài đặt
Trong n8n (khuyên dùng)
1. Vào Settings → Community Nodes
2. Nhấn Install
3. Nhập @bautran1911/n8n-nodes-zalo-oa
4. Nhấn Install và khởi động lại n8n
Thủ công (self-hosted)
npm install @bautran1911/n8n-nodes-zalo-oa
—
Cấu hình Credential
Sau khi cài node, tạo credential Zalo OA API với các thông tin sau:
| Trường | Mô tả |
|——–|——-|
| Credential Name | Tên phân biệt credential này (ví dụ: Zalo OA - Shop Thời Trang) |
| App ID | Lấy tại developers.zalo.me → App của bạn → App ID |
| Secret Key | Lấy tại developers.zalo.me → App của bạn → Secret Key |
| OA Secret Key (Webhook Signature) | Secret key dùng để verify webhook signature của OA (có thể khác Secret Key của App). Nếu bỏ trống node sẽ fallback về Secret Key. |
| Access Token | Xem hướng dẫn bên dưới |
| Refresh Token | Xem hướng dẫn bên dưới |
| n8n Instance URL | URL n8n của bạn, ví dụ: http://localhost:5678 hoặc https://n8n.example.com |
| n8n API Key | Tạo tại n8n → Settings → API → Create an API key |
| Credential ID | Sau khi lưu credential, xem ID trên URL trình duyệt: .../credentials/ |
Khi bạn điền đủ n8n Instance URL, n8n API Key, Credential ID, hành động Refresh Token (Resource Token) gọi PATCH /api/v1/credentials/:id để ghi Access Token và Refresh Token mới. Payload gửi kèm luôn OA Secret Key (Webhook Signature) (giá trị hiện có trong credential) để trường này không bị xóa trống sau mỗi lần refresh. Các hành động gọi API khác không tự refresh token.
—
Lấy Access Token và Refresh Token từ Zalo
Zalo sử dụng OAuth2 kết hợp PKCE để cấp quyền. Có 2 cách lấy token:
> 📌 Thuật ngữ quan trọng:
>
> – Access Token: Có hiệu lực 25 giờ. Dùng để gọi API.
> – Refresh Token: Có hiệu lực 3 tháng. Chỉ dùng 1 lần để lấy Access Token mới (và sẽ nhận Refresh Token mới).
> – Authorization Code: Chỉ dùng 1 lần, hết hạn sau 10 phút.
—
Cách 2: Sử dụng API Explorer (Khuyên dùng)
> 💡 Phù hợp cho: Admin của OA hoặc Admin của Ứng dụng muốn lấy token nhanh mà không cần cấu hình server.
Các bước thực hiện:
1. Truy cập Zalo API Explorer
(Vào Zalo for Developers → Công cụ & Hỗ trợ → API Explorer)
!Truy cập API Explorer
2. Tại màn hình API Explorer, chọn Ứng dụng của bạn
!Chọn ứng dụng trong API Explorer
3. Tại mục Loại access token, chọn OA Access Token
4. Chọn Official Account (OA) mà bạn muốn liên kết và cấp quyền
5. Hệ thống hiển thị trang yêu cầu cấp quyền → kiểm tra các quyền → nhấn Cho phép
6. Sau khi nhấn “Cho phép”, công cụ hiển thị:
– Access Token → nhấn biểu tượng 📋 Copy để lấy
– Refresh Token → nhấn biểu tượng 📋 Copy để lưu lại
!Kết quả Access Token
!Kết quả Refresh Token
7. Dán Access Token và Refresh Token vào tương ứng trong credential n8n
!Điền token vào credential n8n
> ⚠️ Lưu ý: Access Token từ API Explorer hết hạn sau 25 giờ. Hãy lên lịch workflow chạy hành động Refresh Token (Resource Token) định kỳ, hoặc chạy thủ công khi API trả lỗi hết hạn (-124, 3, -216, -220).
—
Cách 1: Sử dụng OAuth v4 (Tích hợp hệ thống)
> 💡 Phù hợp cho: Tích hợp tự động, cần lấy token theo dạng programmatic.
#### Bước 1 — Tạo App trên Zalo Developer
1. Đăng nhập tại developers.zalo.me
2. Tạo ứng dụng mới → lấy App ID và Secret Key
3. Vào mục Official Account → Liên kết OA → liên kết OA của bạn với App
4. Thiết lập Callback URL trong phần cài đặt ứng dụng
#### Bước 2 — Tạo Code Verifier & Code Challenge (PKCE)
Tạo code_verifier (chuỗi ngẫu nhiên)
code_verifier=$(openssl rand -base64 64 | tr -d '=+/' | cut -c1-64)Tạo code_challenge (SHA-256 + Base64 không padding)
codechallenge=$(echo -n "$codeverifier" | openssl sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')
#### Bước 3 — Lấy Authorization Code
Gửi URL sau cho Admin OA để họ nhấn “Cho phép”:
https://oauth.zaloapp.com/v4/oa/permission?appid=YOURAPPID&redirecturi=YOURCALLBACKURL&codechallenge=YOURCODE_CHALLENGE
Zalo sẽ redirect về Callback URL kèm mã code:
https://your-callback.com/callback?code=AUTHORIZATION_CODE
#### Bước 4 — Đổi Code lấy Tokens
curl -X POST https://oauth.zaloapp.com/v4/oa/access_token
-H "Content-Type: application/x-www-form-urlencoded"
-H "secretkey: YOURSECRET_KEY"
-d "appid=YOURAPPID&code=AUTHORIZATIONCODE&granttype=authorizationcode&codeverifier=YOURCODE_VERIFIER"
Response:
{
"access_token": "...",
"refresh_token": "...",
"expires_in": 90000
}
Copy accesstoken và refreshtoken vào credential n8n.
#### Gia hạn Token bằng Refresh Token
curl -X POST https://oauth.zaloapp.com/v4/oa/access_token
-H "Content-Type: application/x-www-form-urlencoded"
-H "secretkey: YOURSECRET_KEY"
-d "appid=YOURAPPID&refreshtoken=YOURREFRESHTOKEN&granttype=refreshtoken"
> ✅ Node n8n có hành động Refresh Token (Resource Token) — bạn không cần chạy lệnh curl thủ công. Xem phần Operations → Refresh Token.
—
Zalo OA Trigger (Webhook)
Node Zalo OA Trigger nhận webhook realtime từ Zalo Official Account. Cổng ra (Main) truyền dữ liệu sang bất kỳ node nào khác (AI Agent, IF, Switch, Code, Set…) để xử lý và phản hồi.
Cấu hình webhook trên Zalo OA
1. Kéo node Zalo OA Trigger vào workflow → copy Production URL.
2. Vào Zalo OA Management → chọn OA → Quản lý ứng dụng → Cấu hình Webhook → dán URL vào và chọn các sự kiện cần nhận.
3. Quay lại n8n, mở node, chọn Events muốn lọc (hoặc All User Send Events để nhận mọi loại tin user gửi).
Tham số
| Tham số | Mô tả |
|———|——-|
| Events | Lọc theo eventname. Option đặc biệt All User Send Events gộp toàn bộ usersend_*. Để rỗng sẽ nhận mọi event. |
| Ignore OA Echo | Bỏ qua event oasend* (và các event có sender.id == recipient.id) để tránh vòng lặp khi node Zalo OA tự phát sinh event. |
| Verify Signature | Xác thực header X-ZEvent-Signature theo chuẩn Zalo: mac = sha256(appId + data + timeStamp + OAsecretKey). Node sẽ lấy timeStamp ưu tiên từ header X-ZEvent-Timestamp (fallback body.timestamp) và dùng OA Secret Key (Webhook Signature) (fallback Secret Key). Vẫn giữ fallback HMAC-SHA256(rawBody, OAsecretKey) cho một số webhook cũ. |
| Simplify | Trả output dạng rút gọn với các field phẳng tiện cho AI (xem bên dưới) thay vì raw body. |
Cấu trúc output (Simplify = ON)
{
"eventname": "usersend_text",
"app_id": "1234567890",
"sender_id": "6123456789",
"recipient_id": "1234567890",
"useridby_app": "",
"timestamp": "1713456789000",
"user_id": "6123456789",
"text": "Shop ơi cho em hỏi giá...",
"msg_id": "abc-xyz",
"attachments": [],
"message": { "text": "...", "msg_id": "...", "attachments": [] },
"raw": { "...": "toàn bộ body gốc" }
}
> 🤖 Các field tiện lợi: userid (tự chọn sender.id hoặc recipient.id tùy event), text, msgid, attachments — dùng trực tiếp làm input cho AI Agent / LLM và đầu vào cho node Zalo OA resource Tin Tư Vấn để phản hồi khách hàng.
—
Workflow chatbot AI với Zalo OA
[Zalo OA Trigger]
│ user_id, text
▼
[AI Agent / LLM] (prompt = "Bạn là nhân viên CSKH... Khách hỏi: {{$json.text}}")
│ output = câu trả lời
▼
[Zalo OA] Resource = Tin Tư Vấn → Operation = Gửi Tin Tư Vấn Dạng Văn Bản
User ID = {{ $('Zalo OA Trigger').item.json.user_id }}
Nội dung = {{ $json.output }}
Mẹo:
oasendtext sau khi bạn gửi reply.text ≤ 500 ký tự và/hoặc enrich thêm context (intent, session data, lịch sử từ Redis/Postgres) trước khi vào AI Agent.$('Zalo OA Trigger').item.json.userid ở node sau cùng để giữ đúng userid gốc, không bị mất qua các bước trung gian.—
Operations
Resource: Thông Tin OA
Resource: Hội Thoại (Conversation)
User ID). Cho phép phân trang thông qua Offset và Count (tối đa 10 tin/lần).Resource: Người Dùng (OA)
User ID.Resource: Tin Tư Vấn (CS Message)
#### Gửi Tin Tư Vấn Dạng Văn Bản
Gửi tin nhắn văn bản tới một người dùng cụ thể thông qua user_id. Dùng cho workflow chatbot AI phản hồi lại tin nhắn khách gửi vào OA.
| Tham số | Bắt buộc | Mô tả |
|———|———-|——-|
| User ID | ✅ | Zalo User ID của người nhận — lấy trực tiếp từ output user_id của Zalo OA Trigger |
| Nội Dung Văn Bản | ✅ | Nội dung tin nhắn văn bản (tối đa 500 ký tự theo Zalo) |
> ⚠️ Điều kiện Zalo: chỉ gửi được tới user đã tương tác với OA trong 7 ngày gần nhất. API endpoint: POST https://openapi.zalo.me/v3.0/oa/message/cs — xem tài liệu Zalo.
#### Gửi Tin Tư Vấn Đính Kèm Ảnh
Gửi tin nhắn đính kèm ảnh (kèm caption tuỳ chọn) tới user_id. Hỗ trợ 2 nguồn ảnh: URL công khai hoặc Attachment ID (đã upload lên Zalo).
| Tham số | Bắt buộc | Mô tả |
|———|———-|——-|
| User ID | ✅ | Zalo User ID của người nhận |
| Nguồn Ảnh | ✅ | URL Ảnh Công Khai hoặc Attachment ID (Đã Upload Lên Zalo) |
| URL Ảnh | ✅ (nếu Nguồn Ảnh = URL) | Link công khai tới ảnh (JPG/PNG, ≤ 5MB theo Zalo) |
| Attachment ID | ✅ (nếu Nguồn Ảnh = Attachment ID) | ID nhận được từ API upload của Zalo |
| Chú Thích (Caption) | ❌ | Văn bản đi kèm ảnh (tuỳ chọn) |
> ⚠️ Cùng điều kiện 7 ngày như tin văn bản. API endpoint: POST https://openapi.zalo.me/v3.0/oa/message/cs với attachment.template_type=media. Xem tài liệu Zalo.
Resource: Tin Nhắn ZBS Template
Gửi ZBS Template Message qua số điện thoại người nhận.
| Tham số | Bắt buộc | Mô tả |
|———|———-|——-|
| Số Điện Thoại Người Nhận | ✅ | Định dạng quốc tế, ví dụ: 84987654321 |
| Template ID | ✅ | ID template đã được phê duyệt trên Zalo OA |
| Dữ Liệu Template (JSON) | ✅ | Object JSON chứa các biến của template |
| Tracking ID | ❌ | Mã theo dõi tuỳ chỉnh (tối đa 48 ký tự) |
| Chế Độ Gửi | ❌ | Gửi Thường (trong hạn mức) hoặc Gửi Vượt Hạn Mức |
Resource: Token
Refresh Token — Làm mới Access Token từ Refresh Token và tự động ghi đè vào credential (khi đã cấu hình n8n API + Credential ID).
Sử dụng khi muốn chủ động làm mới token (ví dụ: chạy định kỳ mỗi 5 ngày).
—
⚠️ Lưu ý: Giới hạn tốc độ gọi API (Rate Limit)
Zalo OA áp dụng các giới hạn tốc độ gọi API (Rate Limit) riêng nhằm duy trì ổn định hệ thống. Việc gọi API với tần suất quá cao (ví dụ: chạy qua Loop/Split in Batches tốc độ cao trong n8n) có thể làm ứng dụng vượt mức cho phép, kết quả là bạn sẽ nhận cảnh báo lỗi (Mã lỗi thông thường là -32).
👉 Tham khảo chi tiết các hạn mức: Giới hạn tốc độ gọi API (Zalo for Developers)
💡 Mẹo khi dùng n8n:
—
Ví dụ sử dụng
Gửi thông báo đặt hàng thành công
Template Data:
{
"customer_name": "Nguyễn Văn A",
"order_id": "DH-2024-001",
"total_amount": "500.000đ",
"delivery_date": "10/04/2024"
}
Cấu hình node:
84987654321123456Tự động refresh token mỗi 5 ngày
Tạo workflow với:
1. Schedule Trigger → mỗi 5 ngày lúc 3:00 sáng
2. Zalo OA node → Resource: Token → Operation: Refresh Token
—
Compatibility
| Phiên bản | Trạng thái |
|———–|———–|
| n8n ≥ 1.0.0 | ✅ Tương thích |
| Node.js ≥ 22 | ✅ Tương thích |
—
Tài nguyên
—
Tác giả
Báu Đẹp Trai
📧 bautran1911@gmail.com
🐙 github.com/bautran1911
—
☕ Ủng hộ tác giả
Nếu node này giúp ích cho công việc của bạn, hãy ủng hộ tác giả một ly cà phê để tiếp tục phát triển và duy trì dự án! 🙏
🏦 Chuyển khoản ngân hàng (Việt Nam)
| Thông tin | Chi tiết |
|———–|———-|
| Ngân hàng | MB Bank (Ngân Hàng Quân Đội) |
| Số tài khoản | 0930113997979 |
| Chủ tài khoản | TRAN NGOC BAU |
| Nội dung CK | donate n8n zalo oa |
📱 Quét QR để chuyển khoản nhanh
MB Bank
> 💡 Bạn cũng có thể dùng MoMo, ZaloPay, hoặc VietQR để chuyển khoản nhanh qua số tài khoản trên.
—
Version History
v1.0.19 (2026-05)
POST /v3.0/oa/message/cs với attachment.template_type=media.v1.0.17 (2026-05)
v1.0.16 (2026-05)
v1.0.15 (2026-05)
Verify Signature của Zalo OA Trigger dùng đúng công thức sha256(appId + data + timeStamp + OAsecretKey) và thêm field credential OA Secret Key (Webhook Signature) (fallback về Secret Key để tương thích ngược).v1.0.14 (2026-04)
POST /v3.0/oa/message/cs) — phục vụ workflow chatbot AI phản hồi tin nhắn khách hàng.X-ZEvent-Signature trên trigger.userid, text, msgid, attachments ở top-level để AI Agent / LLM dùng trực tiếp.v1.0.13 (2026-04)
-216, -220 (bên cạnh -124, 3)
