💬 Kết nối Zalo OA & Chat

Kết nối Zalo Official Account (OA) với Xbook để chat trực tiếp với khách hàng ngay trong hệ thống, đồng bộ người dùng Zalo, gắn họ vào liên hệ (res.partner) và theo dõi hạn mức tin nhắn (quota) của OA. Toàn bộ thao tác nằm trong phân hệ Zalo.

🧩 Chuẩn bị trước khi kết nối

Để kết nối được, bạn cần một Zalo Official Account đã đăng ký trên trang Zalo for Developers và lấy các thông tin sau:

Trường	Ý nghĩa
App ID	Mã ứng dụng Zalo của OA
App Secret	Khóa bí mật ứng dụng, dùng để lấy và làm mới token
OA Secret Key	Khóa bí mật của OA, dùng để xác thực webhook nhận tin

💡 Việc lấy App ID, App Secret và OA Secret Key được thực hiện trên trang quản trị ứng dụng của Zalo, không phải trong Xbook. Hãy giữ kín các khóa này.

⚙️ Bước 1 – Cấu hình kết nối (Pusher & Redirect URI)

Xbook dùng dịch vụ Pusher để nhận tin nhắn theo thời gian thực và cần khai báo Redirect URI cho luồng xác thực OAuth.

1. Vào Zalo → Configuration → Zalo Config.
2. Mở (hoặc tạo) bản ghi cấu hình. Tại nhóm OAuth Configuration, nhập Redirect URI.
3. Tại nhóm Pusher Configuration, nhập Pusher App ID, Pusher Key, Pusher Secret, Pusher Cluster (mặc định ap1) và bật/tắt Pusher SSL theo nhu cầu.
4. Lưu cấu hình.

📷 Cần chèn ảnh: /img/integrations/zalo-oa/01.png — Màn hình Zalo Config với OAuth Configuration và Pusher Configuration.

💡 Redirect URI ở đây phải trùng với URL callback đã khai báo cho ứng dụng trên trang Zalo for Developers thì luồng đăng nhập mới hoàn tất được.

🔑 Bước 2 – Đăng nhập Official Account

Việc khai báo khóa và đăng nhập OA được thực hiện ngay tại màn hình Chat.

1. Vào Zalo → Chat.
2. Nếu OA chưa được kết nối, hệ thống tự hiển thị màn hình Login to Zalo OA. Nhập:
   • App ID
   • App Secret
   • OA Secret Key
3. (Tuỳ chọn) Nhấn Hướng dẫn để xem các bước minh hoạ, hoặc Link để mở trang quản lý ứng dụng Zalo (developers.zalo.me/apps).
4. Nhấn nút Login. Hệ thống lưu khóa vào cấu hình OA rồi chuyển sang trang ủy quyền của Zalo (oauth.zaloapp.com).
5. Đăng nhập tài khoản Zalo và cấp quyền cho ứng dụng truy cập OA của bạn.

Sau khi cấp quyền thành công, Zalo gọi về Redirect URI, hệ thống tự lấy Access Token cùng thông tin OA rồi đưa bạn trở lại màn hình Chat.

📷 Cần chèn ảnh: /img/integrations/zalo-oa/02.png — Màn hình Login to Zalo OA với App ID / App Secret / OA Secret Key.

⚠️ App ID, App Secret, OA Secret Key và Access Token chỉ hiển thị/lưu với người dùng có quyền quản trị hệ thống. Không chia sẻ các giá trị này ra ngoài.

💡 Hệ thống có tác vụ định kỳ Zalo: Làm mới Access Token chạy mỗi ngày để tự gia hạn token bằng Refresh Token, nên bạn không cần đăng nhập lại thường xuyên.

🏢 Bước 3 – Xem thông tin Official Account

Sau khi kết nối, thông tin OA do Zalo trả về được lưu lại để tra cứu.

1. Vào Zalo → Management → Official Account Management → Zalo Official Account.
2. Danh sách hiển thị Application Name, App ID và OA Name. Mở một bản ghi để xem chi tiết (các trường chỉ đọc):

Trường	Ý nghĩa
OA Name	Tên Official Account
OA Description	Mô tả OA
OA Alias	Đường dẫn rút gọn của OA
OA Verified	OA đã được xác thực hay chưa
OA Type	Loại OA: Business / Government Agency
Industry	Ngành nghề của OA
Follower Count	Số người quan tâm OA
Package Name	Tên gói dịch vụ
Valid Through	Ngày hết hạn gói
Access Token	Mã truy cập API (chỉ đọc)

📷 Cần chèn ảnh: /img/integrations/zalo-oa/03.png — Biểu mẫu Zalo Official Account với thông tin OA.

💡 Trên biểu mẫu này có sẵn nút Login ở phần đầu. Dùng nút này để xác thực lại với Zalo khi cần (ví dụ token bị thu hồi).

👥 Bước 4 – Đồng bộ người dùng Zalo

Danh sách người đã tương tác/quan tâm OA được kéo về thành bản ghi Zalo User.

1. Vào Zalo → Management → User Information Management → User List.
2. Nhấn nút Đồng bộ người dùng ở đầu danh sách.
3. Trong cửa sổ đồng bộ, thiết lập điều kiện lọc rồi nhấn Synchronize:

Trường	Ý nghĩa
Offset	Vị trí bắt đầu lấy danh sách
Count	Số người dùng lấy mỗi lần (mặc định 50)
OA follow status	Lọc theo trạng thái quan tâm: All users / Following OA / Not following OA
Last interaction period	Khoảng tương tác gần nhất: Today / Yesterday / Last 7 days / Last 30 days
Tag name	Lọc theo thẻ (nếu có)

Mỗi bản ghi Zalo User lưu các thông tin như: tên hiển thị (Display Name), Zalo User ID, Alias, đang theo dõi OA (Following OA), lần tương tác gần nhất (Last Interaction Date), số điện thoại chia sẻ (Shared Phone) và thẻ (Tags).

📷 Cần chèn ảnh: /img/integrations/zalo-oa/04.png — Cửa sổ Đồng bộ người dùng và danh sách Zalo User.

🔗 Bước 5 – Gắn người dùng Zalo vào liên hệ

Mỗi liên hệ (res.partner) có thể được liên kết với một Zalo User để gộp lịch sử chat về đúng khách hàng.

1. Vào Liên hệ và mở liên hệ cần gắn (hoặc tạo mới).
2. Tìm trường Zalo User (nằm ngay sau Mã số thuế / VAT trên biểu mẫu liên hệ).
3. Chọn người dùng Zalo tương ứng và lưu.

💡 Nên đồng bộ người dùng Zalo trước (Bước 4) để có sẵn danh sách lựa chọn khi gắn vào liên hệ.

💬 Bước 6 – Chat với khách hàng

1. Vào Zalo → Chat để mở giao diện hội thoại.
2. Chọn người dùng Zalo trong danh sách hội thoại để xem lịch sử tin nhắn.
3. Soạn và gửi tin nhắn; tin do khách gửi đến được nhận theo thời gian thực qua Pusher.

Hệ thống ghi nhận tin nhắn với các loại nội dung: văn bản (Text), thoại (Voice), ảnh (Photo), GIF, liên kết (Link/Links), nhãn dán (Sticker) và vị trí (Location); đồng thời phân biệt nguồn gửi là OA Send hay User Send.

⚠️ Zalo áp dụng quy định gửi tin của riêng nền tảng. Một số trường hợp tin sẽ bị từ chối, ví dụ: người dùng chưa từng quan tâm hoặc chưa tương tác với OA trong 7 ngày, người dùng đã chặn tin của OA, vượt hạn mức gửi tin, hoặc gửi tin trong khung giờ ban đêm (22h–6h). Khi đó hệ thống hiển thị thông báo lỗi tương ứng từ Zalo.

📷 Cần chèn ảnh: /img/integrations/zalo-oa/05.png — Giao diện Chat với danh sách hội thoại và khung tin nhắn.

👨‍👩‍👧 Quản lý nhóm hội thoại

1. Vào Zalo → Management → Group Management → Group List.
2. Nhấn nút Đồng bộ Zalo Group để kéo danh sách nhóm của OA về Xbook.

Danh sách hiển thị: tên nhóm (Group Name), Group ID, số thành viên (Total Members) và trạng thái (Status: Enabled / Disabled). Mở một nhóm để xem thêm liên kết tham gia (Join Link) và mô tả (Description).

📷 Cần chèn ảnh: /img/integrations/zalo-oa/06.png — Danh sách Zalo Group sau khi đồng bộ.

📊 Kiểm tra hạn mức tin nhắn (Quota)

Trước khi gửi nhiều tin, bạn nên kiểm tra hạn mức còn lại của OA.

1. Vào Zalo → Management → Official Account Management → Check OA Message Quota.
2. Chọn điều kiện truy vấn:

Trường	Ý nghĩa
Quota Owner	Đối tượng sở hữu hạn mức: OA hoặc App
Product Type	Loại tin: Customer Service (cs) hoặc Transaction
Quota Type	Nguồn hạn mức: gói thuê bao (sub_quota) / mua lẻ (purchase_quota) / khuyến mãi (reward_quota)

3. Nhấn nút Get Quota. Bảng Quota Details sẽ hiển thị các cột: Asset ID, Product Type, Quota Type, Valid Through, Total (tổng) và Remaining (còn lại).

📷 Cần chèn ảnh: /img/integrations/zalo-oa/07.png — Cửa sổ Check OA Message Quota với bảng Quota Details.

💡 Nếu cột Remaining về 0, OA đã hết hạn mức cho loại tin đó và cần nâng cấp gói hoặc mua thêm trên nền tảng Zalo.

Liên quan

• Thông báo Zalo ZNS — gửi tin giao dịch chính thức tới khách
• Mẫu tin Zalo — soạn mẫu tin giao dịch gửi qua OA
• Tạo liên hệ — gắn Zalo user vào khách hàng