Hướng dẫn Facebook Lead Ads | BĐS Store

Tổng quan

Facebook Lead Ads hoạt động như thế nào?

Khi khách hàng điền form trên quảng cáo Facebook, dữ liệu được đẩy về server BĐS Store qua webhook — tự động tạo lead trong CRM và kích hoạt drip follow-up, không cần thao tác thủ công.

Không rời Facebook

Khách điền form ngay trong ứng dụng Facebook/Instagram — tỉ lệ chuyển đổi cao hơn landing page vì không cần mở trình duyệt.

Tự động vào CRM

Mỗi lần có lead mới, hệ thống gọi Graph API lấy chi tiết (họ tên, SĐT, email) rồi tạo bản ghi Lead trong dự án tương ứng.

Kích hoạt Drip ngay

Sau khi lead được tạo, hệ thống tự động enroll vào chuỗi drip follow-up (gọi +24h, Zalo +72h, gọi chốt +168h).

Các bước thực hiện

1Facebook gọi webhook tới /api/webhooks/facebook-leads khi có lead mới.
2Server tra Page ID → lấy Page Access Token → gọi Graph API v19.0 lấy thông tin lead.
3Mapping field_data → name / phone / email → tạo Lead trong project tương ứng.
4Gửi notification real-time lên dashboard và enroll drip sequence.

💡

Tích hợp này hoạt động theo mô hình webhook bất đồng bộ — không có độ trễ đáng kể (thường dưới 5 giây sau khi khách submit form).

Điều kiện cần

Chuẩn bị trước khi bắt đầu

Bạn cần có đủ 3 yếu tố sau trước khi cấu hình. Thiếu bất kỳ yếu tố nào thì webhook sẽ không hoạt động.

Facebook Page đã duyệt

Page đăng ads phải là Page có quyền chạy Lead Ads. Page cá nhân (profile) không được hỗ trợ.

Facebook App (Business type)

Cần tạo App tại developers.facebook.com với loại Business. App phải có quyền pages_read_engagement và leads_retrieval.

Website có HTTPS

Facebook chỉ gọi webhook đến URL HTTPS. Khi test local cần dùng tunnel như ngrok hoặc cloudflare tunnel để có HTTPS endpoint.

Các bước thực hiện

1Đảm bảo bạn là Admin hoặc Editor của Facebook Page muốn kết nối.
2Truy cập developers.facebook.com → My Apps → tạo App mới với loại 'Business'.
3Nếu đang test local: cài ngrok, chạy lệnh 'ngrok http 3388' để lấy HTTPS URL tạm thời.

⚠️

Facebook không gửi webhook đến localhost hay IP nội bộ. Bắt buộc phải có HTTPS public URL khi test.

Bước 1

Tạo Facebook App và cấu hình Webhooks

Facebook App là cầu nối giữa Page của bạn và server BĐS Store. Mỗi business chỉ cần tạo 1 App duy nhất cho tất cả Pages.

Tạo App

developers.facebook.com → My Apps → Create App → chọn loại 'Business' → đặt tên (ví dụ: BDS Lead Sync).

Thêm Webhooks product

Trong App dashboard → Add Product → Webhooks → Setup. Chọn object type là 'Page'.

Đăng ký subscription leadgen

Trong Webhooks → Page → chọn field 'leadgen' → Subscribe. Đây là event Facebook gọi mỗi khi có lead mới.

Các bước thực hiện

1Vào developers.facebook.com/apps → tạo App mới loại Business.
2Dashboard App → Add Product → tìm 'Webhooks' → bấm Set Up.
3Chọn 'Page' trong dropdown object → bấm 'Subscribe to this object'.
4Điền Callback URL: https://your-domain.com/api/webhooks/facebook-leads
5Điền Verify Token: một chuỗi bất kỳ bạn tự nghĩ (ví dụ: bds-store-fb-2024).
6Bấm Verify and Save → nếu thành công, tick chọn field 'leadgen' → Subscribe.

# Thêm vào .env — Verify Token phải khớp với chuỗi bạn điền vào Facebook App
FB_WEBHOOK_VERIFY_TOKEN=bds-store-fb-2024

💡

Sau khi thêm FB_WEBHOOK_VERIFY_TOKEN vào .env, restart server (npm run dev). Facebook sẽ gọi GET /api/webhooks/facebook-leads để verify — nếu trả về 200 nghĩa là OK.

Bước 2

Lấy Page Access Token (không hết hạn)

Page Access Token là chìa khoá để server fetch chi tiết lead từ Graph API. Bạn cần lấy token dài hạn (không có expiry) thay vì short-lived token.

Short-lived User Token

Dùng Graph API Explorer tại developers.facebook.com/tools/explorer → chọn App của bạn → Generate User Access Token → tick permissions: pages_read_engagement, leads_retrieval.

Long-lived User Token

Đổi short-lived thành long-lived (60 ngày) bằng API: GET /oauth/access_token?grant_type=fb_exchange_token.

Page Access Token vĩnh cửu

Từ long-lived User Token, gọi GET /{user-id}/accounts để lấy Page Token. Page Token lấy từ long-lived User Token sẽ không bao giờ hết hạn.

Các bước thực hiện

1Mở Graph API Explorer: developers.facebook.com/tools/explorer
2Chọn App của bạn trong dropdown. Bấm 'Generate Access Token'.
3Tick thêm permissions: pages_read_engagement, leads_retrieval → Allow.
4Copy User Access Token vừa tạo (short-lived).
5Gọi API đổi sang long-lived:
6 GET https://graph.facebook.com/oauth/access_token
7 ?grant_type=fb_exchange_token
8 &client_id={APP_ID}
9 &client_secret={APP_SECRET}
10 &fb_exchange_token={SHORT_LIVED_USER_TOKEN}
11Dùng long-lived token vừa nhận, gọi: GET /me/accounts → tìm Page muốn kết nối → copy 'access_token' của Page đó.

# Lấy Long-lived User Token (thay thế các giá trị {})
curl "https://graph.facebook.com/oauth/access_token\
  ?grant_type=fb_exchange_token\
  &client_id={APP_ID}\
  &client_secret={APP_SECRET}\
  &fb_exchange_token={SHORT_LIVED_USER_TOKEN}"

# Lấy danh sách Pages và Page Access Token
curl "https://graph.facebook.com/me/accounts\
  ?access_token={LONG_LIVED_USER_TOKEN}"

⚠️

Đừng dùng short-lived User Token (hết hạn sau ~2 giờ) làm Page Access Token. Phải qua bước đổi sang long-lived trước.

Bước 3

Kết nối Page trong Dashboard

Sau khi có Page Access Token, thêm Page vào BĐS Store. Mỗi Page có thể gán với một dự án mặc định để tự động phân loại lead.

Page ID

Tìm trong Settings → About của Facebook Page, hoặc trong URL khi bạn quản lý Page. Là chuỗi số dài (ví dụ: 123456789012345).

Dự án mặc định

Lead từ Page này sẽ tự động gán vào dự án bạn chọn. Có thể thay đổi sau, nhưng lead cũ không được cập nhật lại.

Trạng thái Active

Page chỉ nhận webhook khi đang ở trạng thái Active. Tắt để tạm ngừng nhận lead mà không mất cấu hình.

Các bước thực hiện

1Vào Dashboard → Cài đặt → Facebook Lead Ads.
2Bấm 'Thêm Page mới'.
3Điền Page ID (chuỗi số), Tên Page (để dễ nhận ra), và Page Access Token vừa lấy.
4Chọn Dự án mặc định — lead từ Page này sẽ vào dự án đó.
5Bấm Lưu.
6Dùng nút 'Gửi lead thử' để kiểm tra pipeline trước khi chạy ads thật.

💡

Tính năng 'Gửi lead thử' tạo một lead giả trong dự án mà không cần gọi Graph API — dùng để kiểm tra drip và notification hoạt động đúng không.

Mở Cài đặt Facebook →

Bước 4

Đăng ký Page nhận sự kiện webhook

Facebook chỉ gọi webhook khi Page đã được App của bạn subscribe. Đây là bước kỹ thuật cần làm một lần duy nhất cho mỗi Page.

Qua Graph API

POST /{page-id}/subscribed_apps — đăng ký App của bạn lắng nghe sự kiện leadgen trên Page này.

Qua App Dashboard

Webhooks → Page → chọn Page cụ thể → Subscribe. Phương pháp này dễ hơn cho người không quen API.

Kiểm tra subscription

Sau khi đăng ký, tạo một lead test trong Ads Manager để xác nhận webhook được gọi đúng.

Các bước thực hiện

1Dùng Page Access Token, gọi API:
2 POST https://graph.facebook.com/{PAGE_ID}/subscribed_apps
3 ?access_token={PAGE_ACCESS_TOKEN}
4 &subscribed_fields=leadgen
5Kết quả { 'success': true } nghĩa là đăng ký thành công.
6Vào Ads Manager → Tạo campaign → Lead Generation → Tạo Lead Form đơn giản để test.
7Preview form → bấm Submit → kiểm tra Dashboard BĐS Store có lead mới không.

# Đăng ký Page nhận sự kiện leadgen
curl -X POST \
  "https://graph.facebook.com/{PAGE_ID}/subscribed_apps" \
  -d "access_token={PAGE_ACCESS_TOKEN}" \
  -d "subscribed_fields=leadgen"

# Kiểm tra đã đăng ký chưa
curl "https://graph.facebook.com/{PAGE_ID}/subscribed_apps\
  ?access_token={PAGE_ACCESS_TOKEN}"

Bước 5

Tạo Lead Form trên Facebook Ads

Lead Form là form khách hàng điền ngay trong Facebook. Cần đặt tên field đúng để hệ thống mapping được họ tên, SĐT, email.

Field họ tên

Dùng field chuẩn 'Full Name' của Facebook (key: full_name). Hệ thống cũng nhận: name, ho_va_ten, ho_ten.

Field số điện thoại

Dùng field chuẩn 'Phone Number' (key: phone_number). Cũng nhận: phone, so_dien_thoai, sdt, mobile.

Field tuỳ chỉnh

Các field tự định nghĩa (ví dụ: loại căn hộ quan tâm, ngân sách) sẽ được lưu vào raw data của lead để tham khảo.

Các bước thực hiện

1Vào Ads Manager → Tạo Campaign → Objective: Lead Generation.
2Ở cấp Ad → Instant Form → Tạo form mới.
3Thêm Questions → từ thư viện có sẵn: chọn 'Full Name' và 'Phone Number'.
4Đặt tên form rõ ràng (ví dụ: Vinhomes HLX - Lead Form Q1 2025).
5Bấm Finish và Publish.
6Test bằng cách vào URL preview của form → điền thông tin → Submit.

💡

Để test nhanh mà không cần chạy ads thật: vào Ads Manager → Lead Ads Testing Tool (trong Tools menu) → chọn Page + Form → Delete Test Lead → Submit Lead.

Vận hành

Theo dõi và xử lý sự cố

Sau khi setup xong, hệ thống tự động. Nhưng cần biết cách kiểm tra khi lead không vào CRM.

Kiểm tra lastError

Mỗi Page trong cài đặt hiển thị lastError nếu có lỗi gần nhất. Lỗi fetch_failed thường do token hết hạn.

Duplicate 24h

Cùng SĐT submit form 2 lần trong 24 giờ sẽ chỉ tạo 1 lead (dedup). Đây là hành vi có chủ đích để tránh spam.

no_page_config

Webhook nhận event của một Page chưa được kết nối → bỏ qua. Cần thêm Page đó vào Cài đặt.

Các bước thực hiện

1Dashboard → Cài đặt → Facebook → xem cột 'Trạng thái' và 'Lỗi gần nhất'.
2Nếu thấy 'fetch_failed: token expired': cần lấy Page Access Token mới và cập nhật.
3Nếu lead không vào: kiểm tra Page đã đăng ký subscription chưa (Bước 4).
4Nếu muốn test lại không cần chạy ads: Ads Manager → Tools → Lead Ads Testing Tool.

Xem Leads CRM →

Facebook Lead Ads

Facebook Lead Ads hoạt động như thế nào?

Chuẩn bị trước khi bắt đầu

Tạo Facebook App và cấu hình Webhooks

Lấy Page Access Token (không hết hạn)

Kết nối Page trong Dashboard

Tạo Lead Form trên Facebook Ads

Theo dõi và xử lý sự cố

Câu hỏi thường gặp

Sẵn sàng kết nối?