Hướng dẫn cấu hình kết nối Zalo OA trong CMS

Bạn đã có Zalo Official Account (OA) và muốn kết nối với website Dybi? Trong CMS — trang quản trị website — hãy lưu thông tin ứng dụng, đăng ký địa chỉ callback và webhook trên Zalo, rồi cấp quyền cho đúng OA. Sau đó bạn có thể chọn nơi nhận thông báo liên hệ và kiểm tra kết quả gửi.

Callback đưa kết quả cấp quyền trở lại hệ thống; webhook nhận sự kiện từ Zalo, chẳng hạn xác nhận giao tin. Hai địa chỉ có nhiệm vụ khác nhau và đều cần sao chép từ CMS của website đang cấu hình.

1. Chuẩn bị trước khi cấu hình kết nối

• Chưa có OA doanh nghiệp: làm theo hướng dẫn đăng ký và xác thực Zalo OA, sau đó quay lại bài này.
• Chưa có ứng dụng: xem hướng dẫn tạo và quản lý ứng dụng Zalo Developers. Khi đã có ứng dụng nhưng chưa đủ thông số, xem hướng dẫn lấy App ID, App Secret và OA Secret Key. Chuẩn bị thông tin của cùng một ứng dụng; bài đó chỉ rõ vị trí lấy và cách tránh nhầm khóa.
• Dùng tài khoản CMS có quyền vào Cấu hình → Kết nối của đúng website và tài khoản Zalo được phép quản trị OA cần kết nối.
• Nếu bật thông báo liên hệ, kiểm tra trước gói dịch vụ, quyền API và mẫu tin hoặc nhóm GMF sẽ dùng. Được cấp quyền kết nối chưa có nghĩa mọi cách gửi đều đã sẵn sàng.

Không cần tự lấy Access Token hoặc Refresh Token để dán vào CMS. Đây là các mã truy cập mà hệ thống xử lý trong quá trình cấp quyền. Nếu cần giao quyền quản lý OA cho người phụ trách, xem hướng dẫn quản lý Zalo OA.

2. Nhập thông tin ứng dụng và lấy URL trong CMS

1. Đăng nhập CMS của website cần cấu hình.
2. Vào Cấu hình → Kết nối → Zalo OA.
3. Bật công tắc Kết nối Zalo OA. Công tắc lưu ngay; chờ xác nhận rồi mở tab Cấu hình kết nối.
4. Trong khối 1. Thiết lập ứng dụng Zalo, nhập App ID và App Secret đã chuẩn bị. Nhập OA Secret Key của cùng ứng dụng vào ô tương ứng; nếu chưa có, hoàn tất phần Webhook ở bước 4 rồi bổ sung.
5. Sao chép riêng URL callback và URL webhook bằng nút Sao chép. Bấm Lưu cấu hình ứng dụng để ghi các trường đang sửa.

Hai ô URL chỉ đọc và được hệ thống cung cấp theo API đang sử dụng. Hãy lấy địa chỉ ngay trên CMS của bạn, không dùng địa chỉ trên thanh trình duyệt hoặc trong ảnh minh họa. Nếu nút sao chép không hoạt động, chọn nội dung trong ô rồi sao chép bằng bàn phím.

Khối Thiết lập ứng dụng Zalo trong CMS. Ảnh dùng thông tin minh họa; địa chỉ example.test không phải địa chỉ để đăng ký cho website của bạn.

Sau khi lưu, các ô khóa được để trống và báo đã lưu. Điều đó không có nghĩa khóa bị mất: CMS không hiển thị lại khóa bí mật. Khi giữ nguyên ứng dụng, để trống ô khóa sẽ giữ giá trị đã lưu. Hai nút Lưu cấu hình ứng dụng và Lưu thông báo cùng lưu toàn bộ cấu hình Zalo đang sửa, nên cần kiểm tra cả thông tin ứng dụng lẫn nơi nhận trước khi bấm.

3. Đăng ký callback trên Zalo rồi cấp quyền từ CMS

Lưu địa chỉ callback trên Zalo

Callback là địa chỉ nhận kết quả khi quản trị viên cấp quyền OA. Phần này được cài trong ứng dụng trên Zalo for Developers; bạn không nhập callback vào thông tin giới thiệu hay trang hồ sơ OA Manager.

1. Mở ứng dụng có App ID trùng với giá trị vừa lưu ở CMS.
2. Vào Official Account → Thiết lập chung, tìm phần thiết lập đường dẫn yêu cầu cấp quyền.
3. Dán nguyên URL callback từ CMS vào ô Official Account Callback Url.
4. Cập nhật/lưu, mở lại phần thiết lập và đối chiếu địa chỉ với CMS trước khi cấp quyền.

Giữ đầy đủ giao thức HTTPS, tên miền và phần đường dẫn. Không thay bằng trang chủ website, trang đăng nhập CMS hoặc URL webhook. Nếu API kết nối có tên miền khác website, vẫn dùng đúng giá trị hệ thống cung cấp trong ô URL callback.

Thêm và kiểm tra domain trong ứng dụng Zalo

1. Trong đúng ứng dụng trên Zalo for Developers, mở Xác thực domain.
2. Nhập tên miền của URL callback vào ô Domain, không nhập giao thức hoặc phần đường dẫn. Ví dụ URL callback dùng máy chủ api.dybiweb.com thì nhập api.dybiweb.com.
3. Bấm Xác thực và kiểm tra domain xuất hiện trong danh sách đã xác thực. Nếu domain đã có trong danh sách của ứng dụng này, tiếp tục cấu hình callback.

Trong ứng dụng DybiWeb của ví dụ này, api.dybiweb.com đã được xác thực. Nếu bạn dùng ứng dụng khác hoặc Zalo chưa xác nhận thành công, xem phần xác thực domain trong hướng dẫn quản lý ứng dụng Zalo Developers để hoàn tất trước khi tiếp tục.

Ví dụ địa chỉ callback đã lưu trong Official Account → Thiết lập chung. Khi cấu hình website khác, sao chép địa chỉ từ CMS của website đó. Mở ảnh kích thước đầy đủ.

Kiểm tra quyền trước khi kết nối

Ứng dụng cần các nhóm quyền phù hợp với cách gửi thông báo doanh nghiệp sẽ dùng. Người quản lý ứng dụng lưu lựa chọn trên Zalo; Admin OA sẽ xem và chấp thuận trong lượt kết nối bắt đầu từ CMS. Xem cách lựa chọn nhóm quyền trong hướng dẫn quản lý ứng dụng Zalo Developers. Admin OA có thể xem phần chấp thuận và kiểm soát liên kết trong hướng dẫn quản lý Zalo OA.

Nếu trang Zalo hiển thị Code Challenge hoặc State, bạn không cần tự tạo các giá trị này để nhập vào CMS. Bắt đầu lượt cấp quyền bằng nút kết nối ở CMS; hệ thống sẽ chuẩn bị các thông tin xác thực cần thiết.

Kết nối đúng OA của doanh nghiệp

1. Trở lại CMS, bảo đảm App ID và App Secret đã được lưu.
2. Tại khối 2. Kết nối Official Account, bấm Kết nối Zalo OA.
3. Trình duyệt chuyển sang Zalo. Đăng nhập tài khoản quản trị OA, đối chiếu tên ứng dụng, App ID, tên và mã OA. Mở các nhóm quyền để đọc phạm vi. Người có thẩm quyền của doanh nghiệp đọc Điều khoản sử dụng Zalo và Điều khoản sử dụng Mạng xã hội Zalo; nếu đồng ý thì đánh dấu ô chấp thuận và bấm Cấp quyền. Nếu OA hoặc phạm vi quyền chưa đúng, quay lại điều chỉnh trước khi chấp thuận.
4. Chờ trở lại CMS. Đối chiếu Tên OA, OA ID và trạng thái Đã kết nối.
5. Bấm Kiểm tra kết nối để kiểm tra quyền truy cập hiện tại.

Tên và mã OA là thông tin chỉ đọc, được lấy sau cấp quyền. Không nhập OA ID vào ô App ID để cố sửa tên OA. Nếu chọn nhầm OA, dừng cấu hình nơi nhận, ngắt kết nối và kết nối lại với đúng OA.

Tham khảo cơ chế xác thực và ủy quyền của Zalo khi cần kiểm tra phía ứng dụng. Trong CMS Dybi, mã truy cập và mã làm mới được hệ thống xử lý; không cần lấy bằng API Explorer để dán vào biểu mẫu.

Ví dụ: khi kết nối website Dybiweb với OA Công ty Dybicom, sau khi cấp quyền cần đối chiếu tên OA và mã 4133621167770884605 ở CMS. Nếu hiện một OA khác, đừng tiếp tục chọn nơi nhận thông báo. Ngắt kết nối nhầm rồi bắt đầu lại với đúng OA; không sửa App ID thành mã OA để cố đổi tài khoản.

Nút kết nối có thể bị khóa nếu vừa nhập khóa mới mà chưa lưu. Hãy lưu cấu hình, chờ xác nhận rồi kết nối. Nếu đã hủy cấp quyền, phiên hết hạn hoặc cấu hình đổi trong lúc cấp quyền, bắt đầu lại từ nút kết nối trong CMS thay vì tải lại URL callback cũ.

CMS đã nhận đúng OA Công ty Dybicom sau khi cấp quyền. Trạng thái Đã kết nối xác nhận bước cấp quyền; webhook và nơi nhận thông báo cần kiểm tra riêng. Mở ảnh kích thước đầy đủ.

4. Đăng ký webhook và lưu khóa xác thực trong CMS

Callback hoàn tất bước cấp quyền; webhook phục vụ các sự kiện Zalo gửi về sau đó. Để nhận xác nhận giao tin theo mẫu, cấu hình cả URL webhook và OA Secret Key đúng ứng dụng.

1. Trong CMS, sao chép URL webhook ở khối Thiết lập ứng dụng Zalo.
2. Mở cùng ứng dụng trên Zalo for Developers, vào Webhook. Ở dòng Webhook URL, chọn Thay đổi, dán địa chỉ từ CMS rồi bấm Kiểm tra. Chờ Zalo báo máy chủ trả về HTTP 200 OK mới bấm Cập nhật. Nếu báo mã lỗi, xử lý lỗi trước; chỉ dán URL chưa có nghĩa webhook đã được lưu.
3. Ở CMS, nhập OA Secret Key đã chuẩn bị vào ô cùng tên, rồi bấm Lưu cấu hình ứng dụng. Nếu chưa có khóa, mở hướng dẫn lấy các thông số ứng dụng Zalo để hoàn tất rồi quay lại; không dùng App Secret điền thay.
4. Trên Zalo, bật sự kiện cần cho cách gửi đang dùng. Với tin theo mẫu gửi qua số điện thoại, đối chiếu quyền Nhận sự kiện gửi tin qua SĐT và sự kiện người dùng nhận tin qua SĐT.
5. Mở lại phần Webhook để kiểm tra URL đã lưu, sau đó kiểm kết quả ở Lịch sử thông báo trong CMS khi gửi thử.

Tham khảo cách cấu hình Webhook của Zalo và sự kiện xác nhận giao tin qua số điện thoại. Địa chỉ phải là URL công khai HTTPS do CMS cung cấp, không phải trang chủ website.

Ví dụ: bạn đã cấp quyền và CMS báo Đã kết nối, nhưng tin theo mẫu chỉ dừng ở Zalo đã tiếp nhận. Hãy kiểm tra thực tế người nhận, URL webhook, khóa đã lưu và quyền nhận sự kiện; trạng thái kết nối OA không thay thế việc xác nhận giao từng tin.

Không bấm Reset khóa chỉ để kiểm tra kết nối. Nếu khóa đã được đổi trên Zalo, nhập khóa mới vào CMS rồi lưu. Cập nhật riêng OA Secret Key không bắt buộc ngắt OA; nhưng nhập sai khóa sẽ khiến hệ thống không xác thực được sự kiện gửi về.

5. Chọn cách nhận thông báo liên hệ mới

Ở khối 3. Thông báo liên hệ mới, bật Gửi thông báo khi có liên hệ mới. Đây là lựa chọn trong biểu mẫu, cần bấm Lưu thông báo để ghi. Có hai cách nhận: gửi tới số điện thoại bằng dịch vụ tin theo mẫu ZBS Template Message, hoặc gửi vào nhóm chat GMF dành cho OA. Hãy chọn theo người phụ trách và dịch vụ OA được phép sử dụng.

Cách A: Chọn mẫu và nhập số điện thoại nhận

1. Ở Mẫu thông báo, chọn một mẫu đang được phép sử dụng của OA.
2. Nhập ít nhất một và tối đa 20 số di động Việt Nam ở ô Điện thoại nhận. Ngăn cách bằng dấu phẩy, dấu chấm phẩy hoặc xuống dòng. Có thể nhập dạng bắt đầu bằng 0 hoặc 84 theo kiểm tra của biểu mẫu.
3. Bấm Lưu thông báo, mở lại để xác nhận mẫu và nơi nhận.

Mẫu phải phù hợp với dữ liệu liên hệ: mã liên hệ, họ tên, điện thoại, tiêu đề, nội dung và thời gian. Ví dụ, mẫu dùng các tham số name, phone, title, message, time có thể nhận các thông tin tương ứng; những tên khác phải thuộc danh sách được kết nối hỗ trợ. Nếu mẫu yêu cầu dữ liệu không có hoặc giới hạn độ dài không phù hợp, hãy chỉnh mẫu hoặc dữ liệu theo thông báo lỗi.

Phương án gửi theo mẫu đến số điện thoại. Tên OA, mã mẫu và số điện thoại trong ảnh chỉ dùng minh họa.

Ví dụ: một liên hệ mới cần báo cho hai người phụ trách. Khi chọn mẫu và lưu hai số điện thoại hợp lệ của họ, hệ thống tạo hai yêu cầu gửi riêng, mỗi yêu cầu gắn một số nhận. Thành công ở số thứ nhất chưa chứng minh số thứ hai đã nhận; đối chiếu từng dòng trong lịch sử.

Cách B: Không dùng mẫu, chọn nhóm GMF của OA

1. Ở Mẫu thông báo, chọn Không dùng mẫu — gửi đến nhóm GMF.
2. Chọn nhóm trong ô Nhóm GMF. Đây phải là nhóm do OA quản lý và kết nối có quyền truy cập, không phải nhóm Zalo cá nhân bất kỳ.
3. Bấm Lưu thông báo và kiểm tra lại nhóm đã chọn.

Chẳng hạn, doanh nghiệp có nhóm GMF “Tư vấn website” và muốn cả đội cùng theo dõi liên hệ. Một yêu cầu mới tạo một thông báo tới nhóm đã chọn; đây không phải cách gửi riêng từng thành viên. Tin được Zalo tiếp nhận cũng chưa chứng minh mọi thành viên đã nhận hoặc đọc. Có thể xem quyền gửi tin nhóm GMF nếu nhóm không dùng được.

Nút Tải danh sách tải lại mẫu và nhóm của OA đang kết nối. Nếu không có lựa chọn, kiểm tra quyền, trạng thái mẫu/nhóm và đúng OA trước. Lỗi gửi theo mẫu không tự chuyển thành gửi nhóm. Khi đổi nơi nhận, các yêu cầu đã tạo vẫn giữ đích cũ, không tự chuyển sang số hoặc nhóm mới.

6. Gửi thử và đọc đúng kết quả

1. Kiểm tra lại OA, mẫu hoặc nhóm và người nhận. Bảo đảm người nhận biết sẽ có tin thử.
2. Bấm Lưu và gửi thử. Nút này lưu cấu hình rồi tạo yêu cầu gửi tin thật có nhãn GỬI THỬ tới nơi nhận vừa cấu hình. Phí và hạn mức phụ thuộc dịch vụ Zalo đang dùng.
3. Mở tab Lịch sử thông báo, bấm Làm mới và đối chiếu đúng nơi nhận, thời gian và trạng thái.
4. Kiểm tra tin thực tế trên Zalo của số nhận hoặc nhóm được chọn.

Lưu cấu hình không tự gửi tin thử. Thông báo “Đã ghi nhận yêu cầu gửi thử” chỉ xác nhận yêu cầu đã được ghi nhận, chưa phải đã giao tin. Nếu chưa nhận được phản hồi của lần thử trước, CMS có thể hiện nút Lưu và thử lại yêu cầu gửi thử; thao tác này dùng lại yêu cầu đang chờ kiểm tra, giúp tránh tạo thêm tin trùng.

Lịch sử minh họa các kết quả khác nhau. Đối chiếu cả hình thức và nơi nhận, thay vì chỉ nhìn thấy một dòng báo thành công.

• Đang chờ gửi: yêu cầu đã lưu, chờ dịch vụ gửi xử lý.
• Đang gửi: hệ thống đang xử lý; chờ rồi làm mới lịch sử.
• Zalo đã tiếp nhận: nền tảng đã chấp nhận yêu cầu, chưa xác nhận giao tới người nhận.
• Đã giao: hệ thống nhận được xác nhận giao tin hợp lệ cho tin theo mẫu. Trạng thái này không có nghĩa người nhận đã đọc.
• Gửi thất bại: đọc lỗi và kiểm tra quyền, mẫu, nơi nhận hoặc dữ liệu trước khi xử lý tiếp.
• Chưa xác định: có thể tin đã gửi nhưng chưa có kết quả chắc chắn; kiểm tra Zalo và lịch sử trước khi tạo yêu cầu khác.
• Đã hủy: yêu cầu không tiếp tục gửi, chẳng hạn kết nối bị ngắt hoặc OA đã thay đổi.

Danh sách có tối đa 30 dòng mỗi trang và thời gian UTC+7. Tin nhóm không được ghi Đã giao cho từng thành viên chỉ vì API tiếp nhận. Nếu CMS báo dịch vụ gửi đang tạm dừng, bạn vẫn có thể lưu cấu hình nhưng cần người vận hành bật dịch vụ trước khi gửi thử.

Sau khi thử thành công, kiểm tra bằng một yêu cầu liên hệ thử được phép gửi trên biểu mẫu website, rồi đối chiếu nội dung trong CMS và lịch sử Zalo. Giữ thông tin thử dễ nhận biết để không nhầm với yêu cầu thật của khách.

7. Nút chat và thông báo liên hệ hoạt động khác nhau thế nào?

Nếu website đang có nút Zalo trong khối liên hệ Hotline, nút này ưu tiên OA đã kết nối khi kết nối được bật. Việc kết nối không tự thêm một khối giao diện chưa được đặt trên website. Khi không thấy nút chat, nhờ người quản trị kiểm tra vị trí hiển thị của khối liên hệ.

Thông báo liên hệ là lựa chọn riêng: bạn có thể giữ kết nối OA cho nút chat, tắt Gửi thông báo khi có liên hệ mới rồi lưu để dừng thông báo. Khách gửi form thành công nghĩa là hệ thống tiếp nhận yêu cầu; cần kiểm tra riêng kết quả gửi Zalo. Người phụ trách vẫn mở Liên hệ trong CMS để đọc và xử lý đầy đủ.

Chức năng này phục vụ kết nối OA và thông báo liên hệ website. Nó không tự biến liên hệ thành đơn bán POS hoặc một chiến dịch gửi tin tiếp thị hàng loạt.

8. Tắt kết nối, ngắt OA và đổi khóa đúng cách

• Tắt công tắc Kết nối Zalo OA: lưu ngay, ẩn phần thiết lập và dừng gửi qua OA nhưng giữ cấu hình. Tin còn chờ có thể tiếp tục được xử lý khi bật lại nếu các điều kiện gửi vẫn đáp ứng. Nút Zalo trong khối Hotline trở về liên kết/số Zalo cũ nếu trước đó đã cấu hình.
• Ngắt kết nối: bấm Ngắt kết nối, đọc xác nhận rồi chọn Ngắt kết nối OA. Hệ thống bỏ thông tin OA và quyền truy cập đã lưu, tắt thông báo liên hệ, hủy các tin còn chờ. Khóa ứng dụng vẫn được giữ để có thể kết nối lại.
• Đổi App ID hoặc App Secret: ngắt OA trước, nhập và lưu thông tin mới rồi cấp quyền lại. Khi đổi sang App ID khác, nhập khóa của ứng dụng mới; không dựa vào khóa cũ đang báo đã lưu.
• Đổi riêng OA Secret Key: nhập khóa mới ở ô tương ứng rồi lưu; không cần ngắt chỉ vì thay khóa webhook.

Không dùng Ngắt kết nối chỉ để kiểm tra xem OA có hoạt động không, vì thao tác này ảnh hưởng các thông báo còn chờ. Nếu màn hình báo Cần kết nối lại, dùng Kết nối lại OA để cấp quyền mới.

9. Xử lý các lỗi thường gặp

• Kiểm tra webhook báo HTTP 401: máy chủ đang từ chối yêu cầu kiểm tra của Zalo. Kiểm tra đúng URL, thông tin xác thực webhook và cách API tiếp nhận yêu cầu với người triển khai hệ thống. Chỉ tiếp tục khi Zalo kiểm tra thành công và URL được lưu. Domain đã được xác thực hoặc CMS báo Đã kết nối không tự giải quyết lỗi này.
• Không thấy Zalo OA trong trang Kết nối: kiểm tra đúng tài khoản có quyền cấu hình và phiên bản CMS đã có tính năng này.
• Nút kết nối bị khóa: bật kết nối, kiểm App ID, lưu App Secret và các khóa vừa nhập; chờ xác nhận rồi bấm kết nối.
• Không trở lại CMS sau cấp quyền: đối chiếu callback đã đăng ký với URL CMS cung cấp, kiểm đúng ứng dụng/OA và bắt đầu lại từ CMS. Không dùng địa chỉ trang đăng nhập CMS thay callback API.
• Không tải được mẫu hoặc nhóm: kiểm tra OA đang kết nối, quyền API, mẫu được phép dùng hoặc nhóm còn hoạt động; bấm Tải danh sách sau khi xử lý quyền.
• Tin mẫu đã được tiếp nhận nhưng chưa có xác nhận giao: kiểm tra thực tế nơi nhận, URL webhook, OA Secret Key và quyền nhận sự kiện giao qua số điện thoại. Chưa có xác nhận không đủ để kết luận đã giao.
• Cấu hình đã thay đổi ở cửa sổ khác: ghi lại phần đang sửa, tải lại, đối chiếu bản mới rồi lưu; không ghi đè liên tiếp bản cũ.
• Gửi thử thất bại hoặc chưa xác định: đọc lỗi trong lịch sử, đối chiếu Zalo trước khi gửi lại. Nếu cần hỗ trợ, cung cấp App ID, OA ID, bước thao tác và ảnh lỗi đã che khóa/token.

Hoàn tất khi bạn đã kiểm đúng tên/mã OA, đăng ký đúng callback/webhook và lưu đúng khóa trong CMS, thử được nơi nhận phù hợp và đối chiếu kết quả trên Zalo. Để điều chỉnh câu hỏi trên form, xem hướng dẫn cấu hình thuộc tính liên hệ. Nếu website cũng dùng Fanpage, có thể tham khảo hướng dẫn kết nối Facebook trong CMS để quản lý riêng từng kênh.