Để kết nối Zalo Official Account (Zalo OA) với EzyOA, bạn cần tạo ứng dụng trên Zalo for Developers, xác thực tên miền, cấu hình OAuth 2.0 với PKCE và cấp quyền cho OA. Sau khi hoàn tất, EzyOA sẽ nhận, lưu trữ và tự động làm mới access token khi cần để duy trì kết nối với Zalo OA.
Trước khi bắt đầu, hãy bảo đảm bạn có quyền quản trị Zalo OA, quyền quản lý ứng dụng Zalo và một website EzyPlatform đang hoạt động trên tên miền công khai có HTTPS. Trên EzyOA, dịch vụ OA cần được cấu hình với dịch vụ xử lý ZALO, App ID, khóa bí mật, Code Challenge và Code Verifier tương ứng.

Tạo ứng dụng trên Zalo for Developers

Bước đầu tiên là tạo ứng dụng đại diện cho hệ thống EzyOA trên nền tảng Zalo. Truy cập Zalo for Developers, đăng nhập rồi chọn tạo ID ứng dụng mới.
Biểu mẫu tạo ID ứng dụng mới trên Zalo for Developers
Tại trường Danh mục, mở danh sách và chọn lĩnh vực phù hợp nhất với hoạt động của doanh nghiệp hoặc dịch vụ.
Danh sách danh mục ứng dụng trên Zalo for Developers
Sau đó, hoàn thiện tên hiển thị và mô tả, đọc điều khoản của Zalo rồi đánh dấu đồng ý trước khi chọn Tạo ID ứng dụng.
Thông tin mẫu khi tạo ứng dụng Zalo
Các thông tin nên được điền theo mục đích sử dụng thực tế:
  • Tên hiển thị: tên ứng dụng mà người quản trị OA có thể nhận biết.
  • Danh mục: lĩnh vực phù hợp với doanh nghiệp hoặc dịch vụ.
  • Mô tả: mô tả ngắn gọn việc ứng dụng kết nối Zalo OA với hệ thống EzyOA.
  • Điều khoản: đọc và đồng ý với chính sách của Zalo trước khi tạo ứng dụng.
Tên và mô tả nên rõ ràng, thống nhất với dịch vụ thực tế để thuận tiện cho quá trình xét duyệt. Sau khi ứng dụng được tạo, bước tiếp theo là chứng minh bạn có quyền quản lý tên miền mà EzyOA đang sử dụng.

Xác thực tên miền website

Trong trang quản lý ứng dụng Zalo, mở API và Cấp quyền → Xác thực domain, nhập tên miền của website rồi chọn Xác thực.
Màn hình nhập tên miền cần xác thực trên Zalo
Nếu tên miền chưa có bằng chứng sở hữu hợp lệ, Zalo sẽ thông báo chưa xác thực và yêu cầu bạn chọn một phương thức xác minh.
Thông báo tên miền Zalo chưa được xác thực
Zalo cung cấp nhiều phương thức xác thực. Nếu chọn DNS TXT, hãy sao chép chính xác giá trị Zalo cung cấp vào cấu hình DNS, chờ bản ghi được cập nhật rồi thực hiện xác thực lại.
Hướng dẫn xác thực tên miền bằng bản ghi DNS TXT
Nếu chọn thẻ meta, sao chép toàn bộ thẻ do Zalo cung cấp. Trong trang quản trị EzyPlatform, mở phần cài đặt website và tìm trường Bổ sung đầu trang.
Vị trí trường Bổ sung đầu trang trong trang quản trị EzyPlatform
Dán thẻ xác thực Zalo vào trường này, không thay đổi thuộc tính name hoặc giá trị content, rồi lưu cấu hình website.
Thêm thẻ xác thực Zalo vào phần Bổ sung đầu trang
Quay lại Zalo for Developers và chọn xác thực. Website phải truy cập được công khai để Zalo đọc thẻ meta. Khi cấu hình hợp lệ, Zalo sẽ hiển thị thông báo xác thực thành công.
Thông báo xác thực tên miền thành công trên Zalo
Sau khi tên miền đã được xác thực, bạn có thể khai báo địa chỉ callback và thông tin PKCE để Zalo chuyển kết quả cấp quyền về đúng dịch vụ trong EzyOA.

Cấu hình callback và PKCE cho Zalo OA

Trong Zalo for Developers, mở Official Account → Thiết lập chung. Tại đây, Zalo yêu cầu Official Account Callback URL và Code Challenge để tạo đường dẫn cấp quyền.
Màn hình thiết lập callback và Code Challenge cho Zalo OA
Không tự nhập một callback tùy ý. Trong EzyOA, mở EzyOA → Các dịch vụ OA, chọn dịch vụ Zalo cần kết nối và sao chép giá trị Đường dẫn callback xác thực trên trang chi tiết. URL này có dạng:
https://<ten-mien-website>/oa/<ma-dich-vu>/auth-callback
Dán nguyên URL vào trường Official Account Callback URL của Zalo rồi lưu lại. Tên miền trong callback phải trùng với website công khai đã cấu hình cho EzyPlatform và đã được xác thực với Zalo.
Nhập Official Account Callback URL của EzyOA trên Zalo
Để lấy Code Challenge tương ứng, quay lại trang quản trị EzyPlatform, mở EzyOA → Các dịch vụ OA và chọn đúng dịch vụ Zalo.
Danh sách dịch vụ OA và dịch vụ Zalo trong EzyOA
Nếu tạo dịch vụ mới, hãy chọn dịch vụ xử lý ZALO, điền App ID và khóa bí mật của ứng dụng Zalo, sau đó dùng chức năng tạo ngẫu nhiên cặp PKCE để EzyOA sinh đồng thời Code Challenge và Code Verifier. Hai giá trị này là một cặp; không thay riêng một giá trị sau khi đã bắt đầu cấp quyền.
Trên trang chi tiết dịch vụ, sao chép Code Challenge rồi dán vào trường tương ứng trên Zalo for Developers. Code Verifier chỉ được lưu trong EzyOA để đổi mã ủy quyền lấy token, không nhập Code Verifier lên Zalo và không chia sẻ công khai.
Vị trí Code Challenge trên trang chi tiết dịch vụ Zalo của EzyOA
Khi callback và Code Challenge đã được lưu, Zalo có thể tạo URL cấp quyền. EzyOA cũng tự tạo Đường dẫn xác thực từ App ID, callback và Code Challenge của dịch vụ, vì vậy bạn không cần tự ghép các tham số OAuth bằng tay.

Cấp quyền Zalo OA và lấy access token

Trước khi cấp quyền, hãy bảo đảm ứng dụng Zalo đã được kích hoạt hoặc phê duyệt theo yêu cầu của Zalo. Nếu trang cấp quyền trả về lỗi -14029 với nội dung ứng dụng chưa được phê duyệt, hãy kiểm tra trạng thái ứng dụng, quyền sử dụng Official Account API và tài khoản quản trị OA; đây không phải lỗi do EzyOA tạo ra.
Lỗi Zalo -14029 khi ứng dụng chưa được phê duyệt
Sau khi ứng dụng đã sẵn sàng, quay lại trang chi tiết dịch vụ Zalo trong EzyOA. Kiểm tra lại App ID, trạng thái dịch vụ và cặp PKCE trước khi bắt đầu cấp quyền.
Nút Lấy access token trên trang chi tiết dịch vụ Zalo của EzyOA
Chọn Lấy access token. Nút này mở đường dẫn cấp quyền do EzyOA tạo sẵn; không sao chép hoặc chỉnh sửa thủ công URL trên thanh địa chỉ. Zalo sẽ yêu cầu đăng nhập, vì vậy hãy dùng tài khoản có quyền quản trị OA và quét mã QR.
Đăng nhập Zalo bằng mã QR để cấp quyền cho ứng dụng
Sau khi đăng nhập, chọn đúng Official Account cần kết nối và đồng ý cấp các quyền mà ứng dụng yêu cầu. Zalo sẽ chuyển trình duyệt về callback của EzyOA kèm mã ủy quyền.
EzyOA kiểm tra callback và Code Challenge, dùng App ID, khóa bí mật cùng Code Verifier để đổi mã ủy quyền lấy access token và refresh token, sau đó lưu các token vào cấu hình bảo mật của dịch vụ. Khi hoàn tất, trình duyệt được chuyển trở lại trang chi tiết dịch vụ OA trong trang quản trị. Bạn có thể xem thêm quy định về token tại tài liệu Official Account Access Token của Zalo.

Kiểm tra và vận hành kết nối

Sau khi cấp quyền thành công, hãy kiểm tra dịch vụ Zalo đang ở trạng thái Đã kích hoạt. Bạn có thể thử một chức năng cần gọi Zalo OpenAPI, chẳng hạn đồng bộ người quan tâm hoặc gửi tin nhắn trong phạm vi quyền đã được cấp, để xác nhận kết nối hoạt động.
Trong quá trình vận hành, cần lưu ý:
  • EzyOA lưu cả access token và refresh token, đồng thời tự làm mới access token khi token hiện tại hết hạn. Bạn không cần làm mới thủ công theo lịch.
  • Không công khai khóa bí mật ứng dụng, Code Verifier, access token hoặc refresh token.
  • Không tạo lại cặp PKCE hoặc thay callback tùy ý khi kết nối đang hoạt động. Nếu thay App ID, khóa bí mật, callback, Code Challenge, Code Verifier hoặc phạm vi quyền, hãy thực hiện lại quy trình cấp quyền.
  • Nếu refresh token bị thu hồi, hết hiệu lực hoặc tài khoản quản trị không còn quyền với OA, hãy chọn Lấy access token và cấp quyền lại.
  • Chỉ yêu cầu những quyền Zalo OA mà hệ thống thực sự cần sử dụng.
Hoàn thành các bước trên nghĩa là ứng dụng Zalo đã được cấu hình đúng để EzyOA nhận callback OAuth, quản lý token và gọi Zalo OpenAPI cho dịch vụ OA đã chọn.