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 kết nối đúng OA cần dùng (trạng thái Đã kết nối), 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 và chọn đúng OA trên trang của 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 ngay sau khi bạn bấm Cấp quyền trên trang cấp quyền của Zalo, dữ liệu hồ sơ OA xuất hiện sau khi bấm Đồng bộ thông tin 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.

    Mẹo

    Tự chọn đúng OA trên trang cấp quyền của Zalo. Trang này mở ở tab mới. Zalo chọn sẵn OA đầu tiên trong danh sách của bạn, có thể không phải OA bạn đang kết nối, và Viindoo chỉ biết bạn muốn kết nối OA nào qua lựa chọn này. Link phía sau nút Xác thực tài khoản có hiệu lực 10 phút kể từ lúc link được tạo (bấm lại nút sẽ mở lại đúng link cũ và không tính lại 10 phút), và nếu Zalo yêu cầu đăng nhập trước thì thời gian đăng nhập cũng bị tính. Trong khoảng thời gian đó:

    1. Mở danh sách thả xuống cạnh tên OA ở phần đầu trang (một mũi tên nhỏ) và chọn đúng OA bạn đang kết nối. Dòng ngay dưới phần đầu trang ghi tên OA sẽ cấp quyền truy cập: hãy kiểm tra dòng này đúng là OA bạn đang kết nối.

    2. Cuộn xuống cuối trang và tích vào ô đồng ý Điều khoản sử dụng của Zalo.

    3. Bấm nút Cấp quyền.

    Cảnh báo

    Xác nhận tên OA trước khi bấm Cấp quyền: lần đồng bộ sẽ nhập người theo dõi của OA bạn đã chọn.

    Nếu để nguyên OA sai, Viindoo sẽ kết nối với OA đó: sau khi bấm Đồng bộ thông tin OA, tài khoản hiển thị tên và ID của OA đó, Viindoo gửi mọi tin nhắn qua OA này, và lần đồng bộ sẽ nhập người theo dõi của OA đó vào Viindoo thành các liên hệ Zalo, mỗi người theo dõi một liên hệ (hiển thị ở nút Liên hệ có Zalo), tối đa khoảng 10.000 liên hệ cho mỗi lần đồng bộ. Một OA có 3.000 người theo dõi sẽ thêm 3.000 liên hệ.

    Để ngắt kết nối, dùng Xóa phiên OAuth - thao tác đặt lại có chủ đích, được giải thích trong trang "Khắc phục sự cố Zalo OA" - rồi xác thực lại. Thao tác này xóa token và đưa tài khoản về Dự thảo, nhưng không xóa các liên hệ đã nhập: chúng vẫn nằm trong Viindoo.

  6. Sau khi callback về hệ thống, quay lại form và bấm Đồng bộ thông tin OA - thao tác này điền tên OA, ảnh đại diện và các thông tin OA khác vào Viindoo, đồng thời nhập người theo dõi của OA thành các liên hệ Zalo. 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 hiển thị số liên hệ gắn với OA, gồm cả người theo dõi đã nhập.

  7. Xác nhận thanh trạng thái ở Đã kết nối: trạng thái này đã chuyển sang Đã kết nối ngay sau khi bạn bấm Cấp quyền, trước bước sync.

  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:

  • Sau khi bấm Cấp quyền, tab Zalo quay về form tài khoản với thanh trạng thái ở Đã kết nối. Nếu thay vào đó là một trang trắng chỉ có thông báo thì việc xác thực chưa hoàn tất: xem mục "Lỗi thường gặp và cách xử lý" bên dưới.

  • 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.

  • Sau khi bấm Đồng bộ thông tin OA, Tên Zalo OA và ID Zalo OA trong tab Lấy thông tin từ Zalo là của đúng OA bạn định kết nối. Nếu không, bạn đã xác thực nhầm OA và lần đồng bộ đã nhập người theo dõi của OA đó thành các liên hệ Zalo: xem cảnh báo ở bước 5 phía trên.

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

  • Nút Liên hệ có Zalo hiển thị số liên hệ gắn với OA, gồm cả người theo dõi được nhập khi đồng bộ: lớn hơn 0 nếu OA có người theo dõi. Nút này và nút Đồng bộ thông tin OA đã có trên form từ lúc tài khoản còn ở Dự thảo, nên chỉ thấy chúng chưa chứng tỏ đồ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. Tab Zalo hiện "Yêu cầu xác thực không hợp lệ hoặc đã hết hạn.":

    • Nguyên nhân thường gặp: đã quá 10 phút kể từ lúc Viindoo tạo link (10 phút không tính lại khi bạn bấm lại Xác thực tài khoản, vì khi đó link cũ được mở lại), hoặc tab được mở từ một link cũ. Trạng thái tài khoản không thay đổi.

    • Hướng xử lý: đóng tab, quay lại form tài khoản và bấm Xác thực tài khoản lần nữa. Viindoo tự tạo link mới khi link trước đã hết hạn nên không cần đặt lại gì. Không dùng Xóa phiên OAuth cho trường hợp này: thao tác đó xóa token và đưa tài khoản về Dự thảo mà không giải quyết được gì.

  3. Tab Zalo hiện "Lỗi xác thực" và trạng thái tài khoản chuyển sang Lỗi:

    • Nguyên nhân thường gặp: Zalo trả về từ chối thay vì cấp quyền, ví dụ do yêu cầu bị từ chối trên trang cấp quyền, hoặc Viindoo không đổi được quyền đó thành token (khi đó thông báo có thêm lý do ở phía sau). Các thông tin khác của tài khoản không thay đổi. Ngoại lệ duy nhất là lời từ chối đến Viindoo sau 10 phút: tab vẫn hiện cùng thông báo nhưng trạng thái không thay đổi.

    • Hướng xử lý: đóng tab, tải lại form tài khoản và bấm Xác thực tài khoản lần nữa, chọn đúng OA, tích ô đồng ý điều khoản và bấm Cấp quyền. Nếu lý do cũ xuất hiện lại, kiểm tra App ID, nhập lại App Secret sao chép từ ứng dụng Zalo (trường này chỉ hiện dấu chấm nên không thể đối chiếu bằng mắt) và kiểm tra URL callback đăng ký trên Zalo OA console khớp với OAuth Callback URL trên form.

  4. Đồ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.

  5. 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 ở: