Điều kiện chuẩn bị
Trước khi bắt đầu, hãy đảm bảo bạn có:- Quyền quản trị cao nhất (Super Admin) trên Portal của bạn để nhập cấu hình.
- Một tài khoản Zalo OA (Official Account) đã đăng ký với quyền quản trị viên.
- Một tài khoản nhà phát triển đăng ký tại cổng Zalo Developers.
- Một số điện thoại di động Việt Nam đang hoạt động ổn định để đăng ký và nhận xác thực.
Zalo OA là kênh tương tác phổ biến tại Việt Nam. Bạn bắt buộc phải có số điện thoại Việt Nam để hoàn tất đăng ký tài khoản trên nền tảng nhà phát triển của Zalo.
Bước 1: Tạo ứng dụng Zalo (Zalo Application)
Nếu chưa có ứng dụng Zalo, bạn thực hiện tạo mới ứng dụng trên cổng Zalo Developer trước khi liên kết với hệ thống của mình.1
Đăng ký tài khoản trên Zalo Developers
Truy cập Zalo Developers và đăng nhập bằng tài khoản Zalo của bạn. Nếu chưa có tài khoản nhà phát triển, tiến hành đăng ký bằng số điện thoại di động Việt Nam.
2
Tạo ứng dụng mới
Làm theo tài liệu hướng dẫn chính thức từ Zalo hoặc đi đến mục tạo ứng dụng, điền tên ứng dụng hiển thị và mô tả ngắn gọn về sản phẩm của bạn.
3
Kích hoạt trạng thái hoạt động
Sau khi ứng dụng được tạo, hãy chuyển trạng thái của ứng dụng sang Active (Hoạt động) trong giao diện Dashboard của ứng dụng.
4
Sao chép App ID và Secret Key
Trong giao diện Dashboard của ứng dụng Zalo, sao chép mã Application ID (App ID) và Application’s Private Key (Secret Key). Bạn sẽ cần hai thông số này ở bước sau.
5
Kích hoạt các API cần thiết
Truy cập vào mục cấu hình API trong ứng dụng Zalo của bạn và kích hoạt đầy đủ các API liên quan đến gửi/nhận tin nhắn và quản lý tài khoản Zalo OA.
Bước 2: Cấu hình Credentials trên Portal quản trị
Bạn cần nhập thông tin ứng dụng Zalo vào Portal quản trị dưới tư cách Super Admin trước khi có thể kết nối Zalo OA cho khách hàng.1
Mở trang cấu hình kết nối
Đăng nhập vào Portal quản trị của bạn, truy cập mục:Sau đó tìm thẻ cấu hình Zalo.
2
Mở cấu hình Zalo
Nhấn nút Edit trên thẻ Zalo để hiển thị biểu mẫu điền thông tin.
3
Nhập thông tin Credentials
Tại cửa sổ Edit Zalo, nhập đầy đủ thông tin vào các trường sau:
Mã Webhook Verify Token là chuỗi bảo mật do bạn tự quy định. Zalo sẽ gửi kèm mã này trong yêu cầu gửi về để hệ thống của bạn đối chiếu nhằm xác minh nguồn yêu cầu thực sự từ Zalo.
4
Lưu cấu hình
Nhấn Save để lưu lại. Thẻ Zalo lúc này sẽ hiển thị mã Client ID.Sau khi lưu thành công, hệ thống hiển thị hai đường dẫn Auth Callback URL và Webhook URL. Hãy sao chép cả hai đường dẫn này để cấu hình ở các bước tiếp theo.
Bước 3: Xác thực tên miền (Domain Verification)
Zalo yêu cầu xác thực sở hữu tên miền trước khi ứng dụng của bạn có thể tiếp nhận sự kiện webhook. Bước này đảm bảo bạn thực sự làm chủ tên miền nơi portal được cài đặt.1
Lấy tên miền portal từ hệ thống
Sao chép chính xác địa chỉ tên miền portal quản trị của bạn:
2
Cấu hình xác thực tên miền trên Zalo
Đi đến phần thiết lập trên Zalo Developer và làm theo hướng dẫn xác thực tên miền của Zalo. Dán mã thẻ Meta tag do Zalo cung cấp vào phần HTML của website hoặc cấu hình bản ghi DNS tương ứng.
3
Xác nhận trạng thái xác thực
Trạng thái cập nhật tên miền có thể mất vài giây. Nhấn kiểm tra lại trạng thái xác thực trong Dashboard ứng dụng của Zalo sau khoảng 3-5 giây. Bạn có thể cần nhấn kiểm tra lại 2-3 lần để trạng thái được cập nhật mới.
Bước 4: Thiết lập Callback URL và Webhook URL trên ứng dụng Zalo
Bạn cấu hình hai đường dẫn liên kết Zalo đã lấy từ Bước 2 vào ứng dụng Zalo để kích hoạt luồng nhận tin nhắn và sự kiện.1
Nhập Callback URL trên Zalo
Sao chép đường dẫn Auth Callback URL từ trang cấu hình Portal quản trị của bạn, dán vào ô Callback URL trong phần cài đặt ứng dụng Zalo và tích chọn đầy đủ các quyền yêu cầu cho OAuth.
2
Nhập Webhook URL trên Zalo
Sao chép đường dẫn Webhook URL từ trang cấu hình Portal quản trị, dán vào ô Webhook URL trong ứng dụng Zalo. Tích chọn đăng ký nhận các sự kiện sau:
Hướng dẫn kết nối cho người dùng
Sau khi hoàn tất cấu hình ứng dụng trên Zalo Developers và nhập Credentials vào Portal quản trị, khách hàng của bạn có thể tự kết nối Zalo OA của họ. Xem chi tiết tại Hướng dẫn kết nối Zalo OA.Xử lý sự cố thường gặp
Tin nhắn gửi đến Zalo OA không hiển thị trên Inbox
Tin nhắn gửi đến Zalo OA không hiển thị trên Inbox
- Kiểm tra xem đường dẫn Webhook URL đã được cấu hình chính xác trên trang quản trị ứng dụng Zalo chưa.
- Đảm bảo ứng dụng Zalo đã đăng ký đầy đủ các sự kiện bắt buộc (
send_msg,get_msg,follow,unfollow). - Kiểm tra mã Webhook Verify Token cấu hình tại Zalo và Portal quản trị xem đã trùng khớp với nhau chưa.
Xác thực tên miền thất bại
Xác thực tên miền thất bại
- Đảm bảo máy chủ portal của bạn hỗ trợ giao thức bảo mật HTTPS và truy cập công khai bình thường.
- Chờ từ 3-5 giây giữa mỗi lần bấm kiểm tra xác thực.
- Thử chuyển đổi giữa các phương thức xác thực khác nhau (ví dụ: dùng DNS TXT record thay vì dùng thẻ HTML meta tag).
Lỗi trong quá trình cấp quyền xác thực (OAuth)
Lỗi trong quá trình cấp quyền xác thực (OAuth)
- Hãy chắc chắn tài khoản Zalo bạn đang đăng nhập giữ vai trò quản trị viên của trang Zalo OA cần kết nối.
- Đảm bảo đường dẫn Callback URL trên cấu hình ứng dụng Zalo khớp hoàn toàn với đường dẫn trên Portal của bạn.
- Kiểm tra lại mã Client ID và Client Secret cấu hình trên Portal đảm bảo khớp với thông tin App ID và Secret Key của ứng dụng trên Zalo Developers.
Làm thế nào để nhận hỗ trợ nếu sự cố vẫn chưa được khắc phục?
Làm thế nào để nhận hỗ trợ nếu sự cố vẫn chưa được khắc phục?
- Kiểm tra lại lịch sử lỗi (logs) trực tiếp trên máy chủ portal để khoanh vùng nguyên nhân.
- Đảm bảo toàn bộ thông số trong trang Org Settings panel được nhập đầy đủ và chính xác.
- Đảm bảo tài khoản Zalo OA và tài khoản Zalo Developer đáp ứng đầy đủ điều kiện hoạt động của nền tảng Zalo.
- Liên hệ bộ phận hỗ trợ cộng đồng kèm theo mô tả chi tiết lỗi và ảnh chụp màn hình để được trợ giúp.