Hướng dẫn tích hợp Facebook Messenger Conversions API

Hướng dẫn thiết lập tích hợp Facebook Messenger Conversions API để ghi nhận sự kiện chuyển đổi và tracking khách hàng từ Facebook Ads.

Tổng quan

Tích hợp này cho phép:

• Gửi sự kiện chuyển đổi (LeadSubmitted, QualifiedLead) về Meta

• Tự động tạo/linking AdCallNumber khi có events từ Facebook Ads

• Tracking khách hàng qua PSID (Page-Scoped User ID) từ Messenger

• Attribution chính xác cho Facebook Ads campaigns

Yêu cầu trước khi bắt đầu

1. Facebook Business Account: Cần có tài khoản Facebook Business

2. Facebook Page: Cần có Facebook Page cho doanh nghiệp

3. Facebook Developer Account: Đăng ký tại developers.facebook.com

4. Messenger API Integration: Đã tích hợp Messenger API (hoặc sẽ tích hợp)

Bước 1: Tạo Facebook Developer App

1. Truy cập Facebook Developers

2. Click "Create App"

3. Chọn "Business" làm loại app

4. Điền thông tin:

   • App Name: Tên app của bạn (ví dụ: "RealCRM Integration")

   • App Contact Email: Email liên hệ

5. Click "Create App"

Bước 2: Cấu hình Permissions

2.1. Thêm Messenger Product

1. Trong App Dashboard, vào "Add Product"

2. Tìm "Messenger" và click "Set Up"

3. Chọn Facebook Page của bạn

4. Lưu Page Access Token

2.2. Yêu cầu Advanced Access cho page_events permission

1. Vào App Dashboard → Settings → Basic

2. Scroll xuống "App Review" → "Permissions and Features"

3. Tìm page_events permission

4. Click "Request Advanced Access"

5. Điền form yêu cầu:

   • Use Case: "We need to track conversion events from our CRM system for Facebook Ads optimization"

   • How will you use this permission?: Mô tả cách bạn sử dụng để track conversions

6. Submit và chờ approval (thường 1-3 ngày)

Lưu ý: Nếu bạn đã có pages_messaging permission với advanced access, page_events sẽ được tự động approve.

2.3. Yêu cầu "Ads Management Standard Access"

1. Vào App Dashboard → Settings → Advanced

2. Tìm "Marketing API" section

3. Enable "Ads Management Standard Access"

4. Để đủ điều kiện, bạn cần:

   • Thực hiện ít nhất 1500 successful Marketing API calls

   • Error rate dưới 10%

   • Trong vòng 15 ngày qua

Bước 3: Lấy Access Token

3.1. User Access Token (cho testing)

1. Vào Graph API Explorer

2. Chọn app của bạn

3. Chọn "Get User Access Token"

4. Chọn permissions: pages_messaging, page_events

5. Generate token và copy

3.2. Page Access Token

1. Vào App Dashboard → Messenger → Settings

2. Tìm "Access Tokens" section

3. Chọn Page của bạn

4. Copy Page Access Token

5. Token này có quyền page_events nếu đã được approve

3.3. System User Access Token

1. Vào Business Settings → System Users

2. Tạo System User mới hoặc sử dụng existing

3. Assign permissions: pages_messaging, page_events

4. Generate token và lưu an toàn

Bước 4: Lấy Page ID

1. Vào Facebook Page của bạn

2. Click "About" tab

3. Scroll xuống tìm "Page ID"

4. Hoặc sử dụng Graph API Explorer:

   • Query: me?fields=id,name

   • Kết quả sẽ có id field

Bước 5: Tạo Dataset (tự động hoặc thủ công)

Tự động (khuyến nghị)

Dataset sẽ được tạo tự động khi gửi event đầu tiên nếu bạn đã cấu hình FACEBOOK_PAGE_ID.

Thủ công

1. Vào Events Manager

2. Chọn "Data Sources" → "Add Data Source"

3. Chọn "Conversions API"

4. Chọn "Business Messaging" → "Messenger"

5. Chọn Page của bạn

6. Copy Dataset ID

Bước 6: Setup Webhook (tùy chọn)

Nếu bạn muốn nhận messages từ Messenger và tự động tạo AdCallNumber:

1. Vào App Dashboard → Messenger → Settings

2. Tìm "Webhooks" section

3. Click "Add Callback URL"

4. Nhập URL: https://app.smartautocrm.vn/api/webhooks/facebook

5. Verify Token: Tạo một token ngẫu nhiên

6. Subscribe to events:

   • messages

   • messaging_postbacks

   • messaging_optins

7. Save

Verify Webhook

Facebook sẽ gửi GET request để verify:

• hub.mode=subscribe

• hub.verify_token=<your-token>

• hub.challenge=<random-string>

Webhook handler sẽ tự động verify.

Bước 8: Verify Events trong Events Manager

Sau khi gửi events:

1. Vào Events Manager

2. Chọn dataset của bạn

3. Vào "Test Events" tab

4. Trigger một event (tạo customer, thay đổi status, etc.)

5. Kiểm tra xem event có xuất hiện không

Test Events

• LeadSubmitted: Tạo customer mới với source = 'AD' và có facebookClickId hoặc facebookPsid

• QualifiedLead: Thay đổi customer status thành HOT hoặc SUPERHOT

Troubleshooting

Lỗi: "Invalid access token"

• Kiểm tra token có đúng không

• Kiểm tra token có expired không

• Đảm bảo token có quyền page_events

Lỗi: "Permission denied"

• Kiểm tra page_events permission đã được approve chưa

• Kiểm tra token có đúng scope không

Lỗi: "Dataset not found"

• Tạo dataset thủ công trong Events Manager

• Hoặc đảm bảo FACEBOOK_PAGE_ID đã được cấu hình

Events không hiển thị trong Events Manager

• Kiểm tra event_id có unique không (deduplication)

• Kiểm tra event_time có trong quá khứ không (không quá 7 ngày)

• Kiểm tra user_data có đúng format không

• Xem logs trong console để debug

Webhook không nhận được messages

• Kiểm tra webhook URL có accessible từ internet không

• Kiểm tra verify token có đúng không

• Kiểm tra Page có được subscribe events chưa

• Test webhook với Webhook Tester

Best Practices

1. Deduplication: Luôn sử dụng event_id để tránh duplicate events

2. Event Time: Sử dụng timestamp thực tế khi event xảy ra, không phải khi gửi

3. Error Handling: Log tất cả errors và retry failed requests

4. Rate Limiting: Facebook có rate limits, implement retry logic với exponential backoff

5. Security: Rotate tokens định kỳ và store securely

6. Monitoring: Monitor event delivery rate và errors

Support

Nếu gặp vấn đề:

1. Kiểm tra Facebook Conversions API Documentation

2. Kiểm tra logs trong console

3. Verify events trong Events Manager

4. Liên hệ Facebook Support nếu cần

Resources

• Facebook Conversions API Documentation

• Business Messaging Guide

• Events Manager

• Graph API Explorer