Chuyển tới nội dung chính

7h. Zalo Ads Lead Form — Hướng dẫn cấu hình 🔶 EE

🔶 Tính năng Enterprise — bản này dành cho đối tượng doanh nghiệp để bên mình tối ưu riêng, nên bản Community không có phần này.

Đường dẫn: Cài đặt → Kênh & Tự động → Zalo Ads Lead Form (/settings/channels/zalo-ads-leadads) Quyền: Quản trị viên (admin/owner). Số liệu trên ảnh là dữ liệu demo.

Tính năng này tự động kéo khách hàng tiềm năng (lead) từ quảng cáo Zalo Form về CRM: kết nối Official Account (OA), khai báo Form quảng cáo, gán mỗi câu hỏi của form vào trường CRM — sau đó hệ thống poll (lấy) lead mỗi 5 phút và đổ vào Tệp khách hàng. Khử trùng lặp tự động (theo SĐT + thời điểm gửi).

💡 Zalo không có webhook cho form lead, nên CRM lấy lead theo chu kỳ (mặc định 5 phút) thay vì tức thời.

Phần 1 — Chuẩn bị (làm bên ngoài CRM)​

Trước khi cấu hình trong CRM, cần làm các bước sau trong Zalo Developers (developers.zalo.me):

A. Tạo Zalo App + lấy App ID & Secret Key

  1. Vào developers.zalo.me → Ứng dụng của tôi → Tạo ứng dụng mới.
  2. Mở app → tab Thông tin ứng dụng → ghi lại App ID và Secret Key.

B. Xác thực domain (bắt buộc — Zalo chỉ chấp nhận Callback URL trên domain đã xác thực)

Xác thực domain

  1. Trong app, mục API và Cấp quyền → Xác thực domain.
  2. Cột Domain: nhập domain gốc (vd locnguyendata.com) → Xác thực.
  3. Cột Tiền tố URL: nhập đúng tiền tố CRM (vd https://ee.locnguyendata.com/) → Xác thực.

    Cách xác thực: tải file zalo_verifierXXXX.html Zalo cấp, đặt vào source CRM tại frontend/public/ rồi build/deploy để serve được tại https://<domain>/zalo_verifierXXXX.html. Xem chi tiết: HUONG-DAN-CAU-HINH-ZALO-ADS-LEAD-FORM.md Mục 3.

  4. Sau khi xác thực thành công, domain + URL hiện trong "Danh sách domain/URL xác thực" (như ảnh).

C. Cấu hình Official Account Callback URL (bắt buộc — nếu sai sẽ lỗi -14003 Invalid redirect uri)

Cấu hình Official Account Callback Url

  1. Vào mục Official Account → Thiết lập chung → khối "Thiết lập đường dẫn yêu cầu cấp quyền".
  2. Ô Official Account Callback Url: nhập chính xác: 
    https://<tên-miền-CRM>/api/v1/integrations/zalo-ads/oauth/callback
    (vd https://ee.locnguyendata.com/api/v1/integrations/zalo-ads/oauth/callback — https, không dấu / cuối).
  3. Bấm Cập nhật để lưu.

    ⚠️ Hai ô Code Challenge và State ngay dưới để TRỐNG — CRM tự sinh khi kết nối (PKCE), không điền tay. Giá trị này phải khớp tuyệt đối với ZALO_OA_OAUTH_REDIRECT_URI (hoặc ô Redirect URI trong ⚙ Cấu hình CRM).

D. Liên kết Official Account + xin quyền "Quản lý ads"

  1. Cùng trang trên, kéo xuống khối "Chọn quyền cần yêu cầu được cấp từ OA".
  2. Tick Quyền: Quản lý ads (bắt buộc — để CRM gọi API lấy lead form). Nên tick thêm Quản lý thông tin OA (để lấy tên OA hiển thị).

E. Lấy Form ID từ quảng cáo Zalo Form

  1. Vào Zalo Ads → Lead Center → chọn chiến dịch Form → Tải dữ liệu Form.
  2. Copy Form ID (chuỗi số sau search= trên thanh địa chỉ, hoặc trong ô tìm kiếm).

Phần 2 — Cấu hình trong CRM​

Trang Zalo Ads Lead Form

Bước 1 — Mở trang Zalo Ads Lead Form​

Vào Cài đặt → Kênh & Tự động → Zalo Ads Lead Form (mục ① trên menu trái).

Bước 2 — Mở Cấu hình​

Bấm nút ⚙ Cấu hình (mục ②) ở góc phải trên.

Bước 3 — Điền thông tin Zalo App rồi Lưu​

Modal Cấu hình Zalo App

Trong cửa sổ Cấu hình, điền:

  • ③a App ID — App ID lấy ở Phần 1.A.
  • ③b App Secret Key — Secret Key lấy ở Phần 1.A (lưu mã hoá; để trống nếu không đổi).
  • ③c OAuth Redirect URI — hệ thống tự điền theo tên miền đang chạy (chỉ đọc). Bấm Sao chép để lấy giá trị này → dán vào Official Account Callback Url ở Phần 1.C.

    ⚠️ Giá trị tự điền này phải khớp tuyệt đối với Official Account Callback Url trong Zalo App (Phần 1.C). Vì cùng suy từ tên miền nên mặc định đã trùng — chỉ cần copy đúng. Sai → Zalo báo -14003 Invalid redirect uri.

  • Bấm ③d Lưu cấu hình.

Bước 4 — Kết nối OA (OAuth)​

Quay lại trang chính, bấm ＋ Kết nối OA (mục ④). Trình duyệt chuyển sang trang cấp quyền của Zalo. Admin của OA đăng nhập (nếu chưa) → màn hình "Yêu cầu cấp quyền truy cập Official Account" hiện ra:

Admin OA cấp quyền truy cập

  1. ① Chọn đúng OA cần kết nối (dropdown góc phải — kiểm tra App ⇄ OA đúng cặp).
  2. ② Tick "Tôi đã đọc và hoàn toàn đồng ý Điều khoản sử dụng của Zalo…".
  3. Bấm ③ Cấp quyền.

Sau khi cấp quyền, CRM quay lại và hiện OA trong khối "Tài khoản OA đã kết nối" với nhãn xanh Đã kết nối.

⚠️ Yêu cầu về OA: OA phải đã xác thực và đã nâng cấp gói (gói trả phí) thì mới dùng được các API (gồm "Quản lý ads"). Màn cấp quyền có dòng cảnh báo "OA đã xác thực và nâng cấp gói sẽ được sử dụng các API sau". OA chưa xác thực/chưa nâng gói → kết nối có thể thành công nhưng gọi API lấy lead sẽ bị từ chối. Xác thực + nâng gói OA tại oa.zalo.me.

Token OA tự động làm mới (access_token sống 25 giờ, hệ thống refresh hằng ngày). Khi token lỗi, OA hiện nhãn đỏ Lỗi → cần bấm Kết nối lại.

Bước 5 — Thêm Form quảng cáo​

Thêm form + map câu hỏi

Bấm ＋ Thêm form, rồi:

  • ⑤ Form ID — dán Form ID lấy ở Phần 1.C.
  • Chọn Tệp khách hàng đích — lead của form này sẽ đổ vào tệp này.

Bước 6 — Tải câu hỏi​

Bấm ⑥ ⤓ Tải câu hỏi. Hệ thống gọi Zalo lấy danh sách câu hỏi của form và tự gợi ý map (Họ tên → Tên, Số điện thoại → SĐT, Email → Email).

Nếu form chưa có lead nào trong 30 ngày, danh sách câu hỏi có thể rỗng → dùng "Thêm câu hỏi thủ công" để tự nhập.

Bước 7 — Gán câu hỏi vào trường CRM​

Tại bảng ⑦ Map câu hỏi → trường CRM, mỗi câu hỏi chọn 1 trong: Tên / SĐT / Email / Tuỳ chỉnh / Bỏ qua.

  • ⚠️ SĐT là bắt buộc (dùng để khử trùng lặp và tạo lead). Câu hỏi gán "Tuỳ chỉnh" sẽ lưu vào trường tuỳ chỉnh của entry; "Bỏ qua" sẽ không lấy.

Bước 8 — Lưu & bắt đầu đồng bộ​

Bấm ⑧ Lưu & bắt đầu đồng bộ. Form xuất hiện trong bảng Form quảng cáo với trạng thái Đang chạy. Từ đây CRM tự lấy lead mỗi 5 phút.

Phần 3 — Sau khi cấu hình​

  • Lead về tệp: sau mỗi chu kỳ (~5 phút), lead mới của form tự vào Tệp khách hàng đích, đã chuẩn hoá SĐT và khử trùng lặp.
  • Theo dõi: 3 thẻ thống kê 24h ở đầu trang — Lead nhận / Đã xử lý / Lỗi-chưa-map.
  • Đồng bộ thủ công: trong cột Thao tác của mỗi form có nút Sync (kéo ngay không chờ chu kỳ).
  • Sửa mapping: nút ⚙ trong cột Thao tác để tải lại câu hỏi / chỉnh gán field.
  • Bật/tắt form: nút bật-tắt để tạm dừng poll 1 form mà không xoá.

Lỗi thường gặp​

Hiện tượngNguyên nhân & cách xử lý
Bấm "Kết nối OA" báo "Zalo App chưa được cấu hình"Chưa điền App ID/Secret/Redirect ở Bước 3.
Zalo báo -14003 Invalid redirect uriOfficial Account Callback Url (Phần 1.C) chưa khai / khai sai / chưa bấm Cập nhật, hoặc không khớp Redirect URI trong CRM. Khai lại đúng chuỗi + bấm Cập nhật.
Không xác thực được domain / Callback bị từ chốiDomain (vd ee.locnguyendata.com) chưa xác thực ở Phần 1.B → xác thực domain + tiền tố URL trước.
Cột Map hiện "1/4 — thiếu SĐT" (dòng vàng)Form chưa gán câu hỏi nào vào SĐT → mở ⚙ gán lại.
Kết nối OA OK nhưng tải câu hỏi/lấy lead bị từ chốiOA chưa xác thực hoặc chưa nâng cấp gói → API bị chặn. Xác thực + nâng gói OA tại oa.zalo.me.
Form không ra leadOA hiện nhãn Lỗi (token hết hạn → kết nối lại); hoặc form chưa có lead mới; hoặc sai Form ID.
Tải câu hỏi rỗngForm chưa có lead trong 30 ngày → dùng Thêm câu hỏi thủ công.

Ghi chú kỹ thuật: App ID/Secret/Redirect cũng có thể đặt qua biến môi trường ZALO_OA_APP_ID / ZALO_OA_APP_SECRET / ZALO_OA_OAUTH_REDIRECT_URI (xem .env.example), nhưng khuyến nghị cấu hình qua UI để hỗ trợ nhiều tổ chức (mỗi org một cấu hình riêng).