Hướng dẫn sử dụng Facebook Messenger Integration

Tổng quan

Tính năng Facebook Messenger Integration cho phép hệ thống:

• Tự động nhận tin nhắn realtime từ Facebook Messenger qua webhook

• Đồng bộ tin nhắn quá khứ từ Facebook Page

• Lấy thông tin user từ Facebook (tên, ảnh đại diện, giới tính)

• Tự động tạo Ad-Calls và Customers từ tin nhắn Facebook

• Đồng bộ định kỳ để bắt tin nhắn có thể bị miss

Yêu cầu

• Quyền truy cập: HEAD hoặc ADMIN/CEO

• Facebook Page ID và Access Token

• Facebook App đã được cấu hình sẵn bởi hệ thống (không cần tạo mới)

Cấu hình ban đầu

Bước 1: Lấy Facebook Page ID

1. Truy cập Facebook Page của bạn

2. Vào Settings → Page Settings → About

3. Tìm Page ID (dãy số dài, ví dụ: 123456789012345)

4. Copy Page ID này

Hoặc cách khác:

• Vào Settings → Page Info

• Scroll xuống phần Page ID

• Copy ID

Bước 2: Lấy Facebook Page Access Token

1. Truy cập Facebook Graph API Explorer

2. Ở góc trên bên phải, chọn "Meta App" (hoặc App của hệ thống nếu đã được cấu hình)

3. Ở dropdown bên cạnh, chọn Facebook Page của bạn

4. Click "Generate Access Token"

5. Copy Access Token (chuỗi dài bắt đầu bằng EAA...)

Lưu ý quan trọng:

• Access Token có thể hết hạn sau 1-2 giờ (Short-lived Token)

• Để có Long-lived Token (60 ngày), xem phần "Lấy Long-lived Token" bên dưới

Lấy Long-lived Token (Khuyến nghị):

1. Sau khi có Short-lived Token, truy cập:

   https://graph.facebook.com/v21.0/oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_LIVED_TOKEN}

2. Thay thế:

   • {APP_ID}: App ID của hệ thống (liên hệ zalo [phone] để lấy)

   • {APP_SECRET}: App Secret của hệ thống (liên hệ zalo [phone] để lấy)

   • {SHORT_LIVED_TOKEN}: Token vừa lấy ở bước trên

3. Copy access_token từ response (token này có hiệu lực 60 ngày)

Bước 3: Cấu hình trong CRM

1. Truy cập Cài đặt → Tích hợp Facebook (/dashboard/settings/facebook)

2. Nhập thông tin:

   • Facebook Page ID: Dán Page ID đã copy ở Bước 1

   • Facebook Access Token: Dán Access Token đã copy ở Bước 2

   • Facebook Dataset ID (tùy chọn): Để trống, hệ thống sẽ tự động tạo

   • Webhook Verify Token (tùy chọn): Để trống hoặc nhập token tùy ý

3. Bật Kích hoạt và nhấn Lưu

4. Nhấn Kiểm tra kết nối để verify cấu hình

Bước 4: Cấu hình Webhook

Sau khi lưu cấu hình, bạn cần cấu hình Webhook để nhận tin nhắn realtime từ Page của bạn.

Quan trọng: Bạn KHÔNG CẦN tạo Facebook App riêng. Hệ thống đã có Facebook App chung, bạn chỉ cần:

1. Đảm bảo Page của bạn đã được thêm vào App (nếu chưa có)

2. Subscribe Page của bạn vào webhook events

4.1. Kiểm tra và thêm Page vào App (nếu cần)

1. Truy cập Facebook Developers

2. Chọn App của hệ thống (liên hệ zalo [phone] để biết App ID)

3. Vào Messenger → Settings

4. Ở phần "Access Tokens", kiểm tra xem Page của bạn đã có trong danh sách chưa

5. Nếu chưa có:

   • Click "Add or Remove Pages"

   • Chọn Page của bạn

   • Click "Add"

   • Copy Page Access Token của Page bạn (dùng token này trong Bước 2)

4.2. Cấu hình Webhook (chỉ cần làm 1 lần cho App)

Lưu ý: Webhook chỉ cần cấu hình 1 lần trong App. Nếu admin đã cấu hình rồi, bạn có thể bỏ qua bước này.

1. Vào Messenger → Settings → Webhooks

2. Kiểm tra xem đã có Callback URL chưa:

   • Nếu đã có: Bỏ qua bước 3-6, chuyển sang bước 7

   • Nếu chưa có: Tiếp tục bước 3

3. Click "Add Callback URL" hoặc "Edit" nếu đã có

4. Nhập thông tin:

   • Callback URL: https://app.smartautocrm.vn/api/webhooks/facebook

   • Verify Token: Nhập token bạn đã đặt trong Bước 3 (hoặc để trống nếu không đặt)

5. Click "Verify and Save"

6. Ở phần "Webhook Fields", chọn các events cần subscribe:

   • ✅ messages (bắt buộc)

   • ✅ messaging_postbacks (tùy chọn, nếu dùng buttons)

7. Click "Save"

4.3. Subscribe Page của bạn vào Webhook

Sau khi webhook đã được cấu hình, bạn cần subscribe Page của bạn:

1. Vẫn ở trang Messenger → Settings → Webhooks

2. Tìm phần "Subscription Fields" hoặc "Page Subscriptions"

3. Tìm Page của bạn trong danh sách

4. Đảm bảo Page của bạn đã được subscribe các events:

   • ✅ messages

   • ✅ messaging_postbacks (nếu cần)

5. Nếu Page chưa được subscribe, click "Subscribe" hoặc toggle để bật

Lưu ý:

• Webhook URL phải accessible từ internet (không dùng localhost)

• Verify Token phải khớp với token trong CRM (nếu có đặt)

• Mỗi Page cần được subscribe riêng vào webhook events

• Sau khi subscribe, Facebook sẽ gửi test event để kiểm tra

• Nếu có nhiều HEAD với nhiều Page khác nhau, tất cả đều dùng chung 1 webhook URL, nhưng mỗi Page cần được subscribe riêng

Sử dụng các tính năng

1. Nhận tin nhắn realtime (Tự động)

Sau khi cấu hình webhook, hệ thống sẽ tự động nhận và xử lý tin nhắn mới từ Facebook Messenger:

• Tự động tạo Ad-Call khi có tin nhắn mới

• Lấy thông tin user từ Facebook (tên, ảnh, giới tính)

• Tự động tạo Customer nếu tin nhắn có số điện thoại

• Link Ad-Call với Customer nếu số điện thoại trùng khớp

Lưu ý: Tin nhắn phải chứa số điện thoại để hệ thống có thể tạo Customer tự động.

2. Đồng bộ tin nhắn quá khứ

Khi nào cần đồng bộ?

• Khi mới kết nối Facebook Page lần đầu

• Khi muốn import tin nhắn cũ vào hệ thống

• Khi nghi ngờ có tin nhắn bị miss

Cách thực hiện:

1. Truy cập Cài đặt → Tích hợp Facebook (/dashboard/settings/facebook)

2. Cuộn xuống phần "Đồng bộ tin nhắn Facebook"

3. Nhấn nút "Đồng bộ ngay"

4. Hệ thống sẽ bắt đầu đồng bộ tin nhắn quá khứ

Theo dõi quá trình đồng bộ:

• Trạng thái hiện tại: Hiển thị trạng thái sync (Đang xử lý, Hoàn thành, Thất bại)

• Progress bar: Hiển thị tiến độ khi đang sync

• Số tin nhắn đã xử lý: Cập nhật realtime

• Lịch sử đồng bộ: Xem các lần đồng bộ trước đó

Các loại đồng bộ:

• Đồng bộ ban đầu (INITIAL): Đồng bộ toàn bộ tin nhắn khi setup lần đầu

• Đồng bộ thủ công (MANUAL): Đồng bộ khi người dùng nhấn "Đồng bộ ngay"

• Đồng bộ định kỳ (PERIODIC): Tự động chạy mỗi 6 giờ (cần cấu hình cron job)

3. Xem thông tin user từ Facebook

Thông tin user từ Facebook sẽ được hiển thị tại:

• Trang chi tiết Customer: Hiển thị tên, ảnh đại diện, giới tính từ Facebook

• Trang chi tiết Ad-Call: Hiển thị thông tin user nếu có

Thông tin hiển thị:

• Tên đầy đủ (first_name + last_name)

• Ảnh đại diện

• Giới tính

• Ngôn ngữ/địa phương

• PSID (Page-Scoped User ID)

• Thời gian đồng bộ lần cuối

4. Xử lý số điện thoại từ tin nhắn

Hệ thống tự động extract số điện thoại từ tin nhắn với các format:

• 0xxxxxxxxx (10-11 chữ số)

• +84xxxxxxxxx (international format)

• 0xxx-xxx-xxx (có dấu gạch ngang)

• (0xxx) hoặc [0xxx] (trong ngoặc)

• SĐT: 0xxx, Phone: 0xxx, Tel: 0xxx (có prefix)

Ví dụ tin nhắn hợp lệ:

Xin chào, số điện thoại của tôi là 0912345678
Hoặc: SĐT: [phone]
Hoặc: (0912345678)

Xử lý lỗi thường gặp

1. Sync không bắt đầu

Nguyên nhân:

• Đã có sync đang chạy

• Access token không hợp lệ

• Page ID không khớp với cấu hình

Giải pháp:

• Kiểm tra trạng thái sync hiện tại

• Verify lại Access Token

• Đảm bảo Page ID đúng

2. Sync bị lỗi (FAILED)

Nguyên nhân:

• Access token hết hạn

• Rate limit từ Facebook

• Lỗi kết nối

Giải pháp:

• Kiểm tra lỗi trong phần "Lịch sử đồng bộ"

• Refresh Access Token nếu cần

• Đợi một lúc rồi thử lại (nếu bị rate limit)

3. Không nhận được tin nhắn realtime

Nguyên nhân:

• Webhook chưa được cấu hình đúng

• Webhook URL không accessible

• Verify Token không khớp

• Page chưa được subscribe webhook events

Giải pháp:

• Kiểm tra webhook configuration trong Facebook Developer App

• Verify webhook URL có thể truy cập được (không dùng localhost)

• Đảm bảo Verify Token khớp với token trong CRM

• Kiểm tra Page đã được subscribe events "messages" chưa

• Liên hệ admin để kiểm tra App configuration nếu cần

4. Không lấy được thông tin user

Nguyên nhân:

• Access token không có quyền pages_read_user_content

• User đã chặn Page

• PSID không hợp lệ

Giải pháp:

• Kiểm tra permissions của Access Token

• Verify user vẫn có thể nhắn tin với Page

• Hệ thống sẽ tiếp tục hoạt động dù không lấy được profile (graceful degradation)

5. Số điện thoại không được extract

Nguyên nhân:

• Format số điện thoại không chuẩn

• Số điện thoại không phải format Việt Nam

Giải pháp:

• Đảm bảo số điện thoại theo format: 0xxxxxxxxx (10-11 chữ số)

• Hoặc format: +84xxxxxxxxx

• Có thể thêm prefix như "SĐT:", "Phone:" để dễ nhận diện

Best Practices

1. Đồng bộ ban đầu

• Nên chạy "Đồng bộ ban đầu" ngay sau khi setup để import tin nhắn cũ

• Đồng bộ ban đầu có thể mất nhiều thời gian nếu có nhiều tin nhắn

• Có thể giới hạn số lượng conversations để test trước

2. Đồng bộ định kỳ

• Nên cấu hình cron job để chạy mỗi 6 giờ

• Đồng bộ định kỳ chỉ sync tin nhắn mới (từ lần sync cuối)

• Giúp bắt các tin nhắn có thể bị miss do webhook issues

3. Quản lý Access Token

• Access Token có thể hết hạn, cần refresh định kỳ

• Nên lưu Long-lived Access Token (60 ngày) thay vì Short-lived (1 giờ)

• Có thể dùng Page Access Token thay vì User Access Token

4. Monitoring

• Thường xuyên kiểm tra "Lịch sử đồng bộ" để phát hiện lỗi

• Monitor số lượng tin nhắn được xử lý

• Kiểm tra logs nếu có vấn đề

Giới hạn và Lưu ý

Rate Limiting

• Facebook có rate limits nghiêm ngặt

• Hệ thống đã implement retry logic với exponential backoff

• Nếu sync bị rate limit, sẽ tự động retry sau một khoảng thời gian

Data Privacy

• Tuân thủ Facebook Platform Policy

• Không lưu thông tin nhạy cảm không cần thiết

• User có thể yêu cầu xóa dữ liệu

Permissions

• Cần pages_messaging permission để đọc tin nhắn

• Cần pages_read_user_content để lấy user profile

• Có thể cần App Review cho production

Hỗ trợ

Nếu gặp vấn đề, vui lòng:

1. Kiểm tra logs trong console

2. Xem "Lịch sử đồng bộ" để tìm lỗi cụ thể

3. Verify cấu hình Facebook App và webhook

4. Liên hệ admin để được hỗ trợ

Tài liệu tham khảo

• Facebook Messenger Platform

• Graph API Conversations

• Graph API User Profile

• Webhooks Guide