Chuyển đến nội dung chính
Tích hợp cổng kết nối Zalo Official Account (Zalo OA) lên portal giúp khách hàng của bạn có thể quản lý tin nhắn, tiếp nhận quan tâm và tự động phản hồi khách hàng qua Zalo OA ngay trên giao diện CSKH tập trung.

​
Đ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.
zalo_developers_portal_homepage_login
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.
zalo_developers_create_new_application_form
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.
zalo_developers_application_status_active
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.
zalo_app_dashboard_app_id_secret_key
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.
zalo_app_api_settings_enabled_apis_list

​
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:
https://app.chatconnectx.com/manage/integrations
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.
chatbotx_edit_zalo_modal
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:
TrườngMô tảNơi lấy thông tin
Client IDMã ID ứng dụng ZaloZalo Developers → Dashboard ứng dụng
Client SecretKhóa bảo mật ứng dụngZalo Developers → Dashboard ứng dụng
API VersionPhiên bản API sử dụngVí dụ: v1.0
Webhook Verify TokenChuỗi ký tự bảo mật xác thực webhookBạn tự tạo một chuỗi ngẫu nhiên
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.
fill-in-the-zalo-credentials
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.
Image

​
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:
app.chatconnectx.com
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.
zalo_developers_domain_verification_meta_tag_setup
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.
zalo_developers_domain_verification_status_confirmed

​
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.
zalo_app_settings_callback_url_permissions_configuration
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:
send_msg
get_msg
follow
unfollow
zalo_app_webhook_url_event_subscriptions

​
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

  • 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.
  • Đả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).
  • 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.
  1. 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.
  2. Đảm bảo toàn bộ thông số trong trang Org Settings panel được nhập đầy đủ và chính xác.
  3. Đả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.
  4. 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.