Cấu hình Zalo OA

Thông tin bài hướng dẫn

Đối tượng: Admin/IT
Thời gian: 10-20 phút cho lần cấu hình đầu tiên
Kết quả: Tài khoản OA vào trạng thái Connected, profile OA được đồng bộ, có URL callback/webhook để cấu hình tại Zalo OA console

Vì sao cần làm đúng thứ tự

Nếu bấm xác thực OAuth trước khi điền đúng App ID và App Secret, hoặc test webhook trước khi OA kết nối hoàn tất, quá trình verify bên Zalo có thể thất bại. Khi đó đội vận hành dễ mất thời gian truy ngược lỗi dù nguyên nhân nằm ở thứ tự thao tác.

Luồng thao tác đúng là:

Checklist thao tác nhanh (đúng thứ tự)

  1. Tạo bản ghi OA Vào màn hình Accounts và tạo mới một bản ghi Zalo Account.

  2. Nhập và lưu thông tin ứng dụng Điền App ID + App Secret, sau đó bấm Save.

  3. Xác thực kết nối Bấm Xác thực tài khoản để thực hiện OAuth với Zalo.

  4. Đồng bộ hồ sơ OA Quay lại Viindoo và bấm Đồng bộ thông tin OA.

  5. Cấu hình webhook sau cùng Chỉ cấu hình/test webhook sau khi account đã kết nối thành công.

Mẹo

Dấu hiệu làm đúng: trạng thái OA chuyển sang Đã kết nối, có dữ liệu hồ sơ OA, và webhook test thành công sau bước sync.

Điều kiện trước khi bắt đầu

  1. Người thao tác có quyền Zalo: Quản trị viên.

  2. Đã có OA hoạt động bên Zalo và có App ID, App Secret.

  3. Đúng company vận hành OA trong môi trường multi-company.

Thiết lập bắt buộc bên Zalo OA và Zalo App

Chỉ cấu hình trong Viindoo là chưa đủ. Để OA gửi/nhận qua OpenAPI, phía Zalo cần hoàn tất bộ tài khoản và cấp quyền trước.

  1. Tạo và xác thực Zalo Official Account (OA) theo hướng dẫn chính thức của Zalo OA.

  2. Tạo Zalo App (ứng dụng trên nền tảng Zalo) để lấy App ID và App Secret.

  3. Thực hiện bước xác thực và cấp quyền cho ứng dụng theo tài liệu nhà phát triển của Zalo.

  4. Nếu dùng ZBS template message, chuẩn bị thêm ZBS Account và liên kết: - ZBS Account <-> OA - ZBS Account <-> Zalo App

  5. Đảm bảo admin nắm quyền trên các tài khoản liên quan (OA/App/ZBS). Các admin này có thể là khác người, nhưng phải phối hợp đúng quyền.

Ghi chú

Với khách hàng lần đầu tích hợp, phần khó thường nằm ở bước tạo App, cấp quyền, và liên kết OA-App-ZBS. Nên kiểm tra xong phần này trước khi quay lại bước OAuth trong Viindoo.

Xem thêm

Các bước cấu hình trong Viindoo

  1. Vào menu Zalo > Configuration > Accounts, tạo mới hoặc mở một bản ghi Zalo Account.

  2. Nhập các trường bắt buộc: - Name - App ID - App Secret - Company và Allowed Companies (nếu dùng multi-company)

  3. Lưu bản ghi.

  4. Dùng OAuth Callback URL hiển thị trên form để cấu hình callback trong OA console.

  5. Bấm Xác thực tài khoản để mở flow xác thực OAuth. Bước này cấp quyền cho Viindoo gửi/nhận thay mặt OA — thiếu bước này API Zalo từ chối mọi request.

  6. Sau khi callback về hệ thống, quay lại form và bấm Đồng bộ thông tin OA — cập nhật tên OA, ảnh đại diện và token về Viindoo. Sau khi sync thành công, tab Lấy thông tin từ Zalo có dữ liệu và nút Liên hệ có Zalo sẵn sàng dùng.

  7. Xác nhận trạng thái chuyển sang Đã kết nối.

  8. Sau khi đã kết nối thành công, dùng Webhook URL hiển thị trên form để cấu hình webhook trong OA console.

Zalo OA Console mục Official Account hiển thị trường Official Account Callback Url để cập nhật đường dẫn callback từ Viindoo Zalo OA Console mục Webhook hiển thị Webhook URL và danh sách sự kiện webhook có thể bật/tắt và test Form tạo mới Zalo Account với khối hướng dẫn onboarding và các trường bắt buộc Tab Phê duyệt OAuth hiển thị URL Callback và URL Webhook để cấu hình bên Zalo OA console

Ghi chú

Trên form onboarding có lưu ý rõ: chỉ test webhook sau khi bước kết nối OA hoàn tất; test sớm có thể fail ở bước verify.

Cấu hình module mở rộng trong Settings

Vào Zalo ‣ Cấu hình ‣ Cài đặt và bật theo nhu cầu vận hành thực tế:

Tính năng

Dùng khi

Trang HDSD

Mẫu Zalo OA (ZBS)

Đội CS/Marketing cần tạo, nộp duyệt và gửi mẫu tin ZBS tới khách hàng.

Đăng ký và quản lý Mẫu tin ZBS (Admin/IT)

Tích hợp Zalo với Hội thoại nghiệp vụ (Cầu nối Chatter)

Cần lưu lịch sử hội thoại Zalo vào chatter của chứng từ nghiệp vụ (đơn bán, hóa đơn, ticket) để các phòng ban theo dõi cùng.

Trả lời tin nhắn từ Zalo OA

Zalo - Sale Templates / Zalo Accounting Template Pack / Zalo Helpdesk Template Hub

Đội Sales/Kế toán/Helpdesk cần gửi thông báo qua Zalo từ chứng từ tương ứng.

Gửi mẫu tin ZBS từ đơn bán, Gửi yêu cầu thanh toán Zalo từ hóa đơn, Cập nhật ticket Helpdesk qua Zalo

Zalo CRM Template Pack

Bạn muốn hội thoại Zalo đổ về CRM — lead tạo từ chat được gắn nguồn Zalo để theo dõi chiến dịch.

Bắt đầu với Zalo OA

Chat trực tuyến Zalo

Website cần nút chat Zalo nổi để khách truy cập nhắn tin trực tiếp.

Nút chat Zalo trên website

Xác thực OAuth Zalo

Portal khách hàng cần nút đăng nhập bằng tài khoản Zalo, giảm ma sát đăng nhập.

Đăng nhập portal bằng Zalo

Sau khi bật, nhấn Save rồi kiểm tra lại màn hình để xác nhận tính năng đã khả dụng.

Nếu một module chưa có trong hệ thống, màn hình sẽ hiển thị link Mua hoặc tìm hiểu thêm.

Màn hình Cài đặt Zalo — phần Tiện ích Zalo với danh sách các tiện ích mở rộng và trạng thái bật/tắt

Checkpoint hoàn thành đúng

Mẹo

Kiểm tra cấu hình hoàn thành đúng:

  • Bản ghi OA ở trạng thái Đã kết nối và có thông tin hồ sơ ở tab Lấy thông tin từ Zalo.

  • Tab Phê duyệt OAuth hiển thị Callback URL, Webhook URL, Token Valid, Token Expires At.

  • Nút Đồng bộ thông tin OA và Liên hệ có Zalo hiển thị trên form sau khi đồng bộ thành công. Nút Nhật ký API hiển thị độc lập với trạng thái kết nối.

Checkpoint hoàn thành — trạng thái Đã kết nối, hồ sơ OA đầy đủ tại tab Lấy thông tin từ Zalo, nút Đồng bộ thông tin OA và Liên hệ có Zalo sẵn sàng

Lỗi thường gặp và cách xử lý

  1. Không thấy nút Xác thực tài khoản/Đồng bộ thông tin OA hoặc không vào được menu Cấu hình: - Nguyên nhân thường gặp: tài khoản chưa có quyền quản trị Zalo hoặc chưa có quyền quản trị hệ thống để mở trang Settings. - Hướng xử lý: kiểm tra lại role user.

  2. OAuth callback báo invalid/expired state: - Nguyên nhân thường gặp: link xác thực cũ hết hạn hoặc luồng OAuth bị gián đoạn. - Hướng xử lý: dùng Xóa phiên OAuth, sau đó thực hiện lại từ bước Xác thực tài khoản.

  3. Đồng bộ thông tin OA lỗi: - Nguyên nhân thường gặp: App ID/App Secret sai hoặc token không hợp lệ. - Hướng xử lý: kiểm tra lại thông tin app, xác thực lại OAuth, rồi sync lại profile.

  4. Webhook verify lỗi ngay sau khi khai báo: - Nguyên nhân thường gặp: test webhook trước khi OA thật sự connected. - Hướng xử lý: xác nhận trạng thái Đã kết nối trước, rồi test lại webhook.

Phạm vi của trang này

Trang này chỉ bao phủ cấu hình kết nối OA và bật extension. Các nghiệp vụ vận hành tiếp theo xem ở: