Tổng quan

Người dùng nhắn Page  ->  Facebook  ->  POST {web-url}/api/v1/oa/{code}/webhook  ->  EzyOA
EzyOA trả lời         ->  POST https://graph.facebook.com/{version}/me/messages?access_token=<Page Access Token>
Admin bấm nút         ->  Facebook Login  ->  GET {web-url}/oa/{code}/auth-callback  ->  EzyOA lưu Page Access Token

Chuẩn bị

• Một Facebook Page mà tài khoản Facebook của bạn có quyền quản trị.
• Tài khoản Facebook có quyền tạo app tại https://developers.facebook.com.
• Website EzyOA có địa chỉ HTTPS công khai (Facebook không gọi được localhost). Khi chạy local có thể dùng ngrok hoặc cloudflared để có URL HTTPS tạm.
• Trong EzyOA, cấu hình web url (địa chỉ web của hệ thống) đúng với domain công khai, vì Webhook URL và Callback URL đều được tạo từ giá trị này.

Tạo app trên Facebook

Giao diện của Meta thay đổi thường xuyên, tên menu có thể khác đôi chút.

Tạo app và thêm sản phẩm

1. Vào https://developers.facebook.com -> My Apps -> Create App.
2. Chọn use case liên quan đến nhắn tin (ví dụ Engage with customers on Messenger from Meta) hoặc Other -> loại app Business.
3. Đặt tên app rồi tạo app.
4. Đảm bảo app có 2 sản phẩm: Messenger (để cấu hình webhook) và Facebook Login (để đăng nhập OAuth).

Lấy App ID và App Secret

1. Vào App settings -> Basic.
2. App ID -> dùng cho trường Mã ứng dụng.
3. App Secret -> bấm Show (Facebook có thể yêu cầu nhập lại mật khẩu) -> dùng cho trường Khoá bí mật.

Verify Token

Khai báo OAuth Redirect URI

1. Vào Facebook Login -> Settings.
2. Ở ô Valid OAuth Redirect URIs, thêm URL callback của EzyOA:

https://<web-url>/oa/<code>/auth-callback

3. Bật Client OAuth Login và Web OAuth Login, rồi lưu.

Nếu app của bạn dùng Facebook Login for Business, luồng đăng nhập dùng config_id thay cho danh sách quyền. Khi đó cần chọn loại app/use case dùng Facebook Login thông thường để nút OAuth của EzyOA hoạt động.

4. Điền form OA Service Setting trong EzyOA

5. Lấy Page Access Token bằng OAuth

1. Mở trang chi tiết của dịch vụ vừa tạo. Dòng Auth url và nút Fetch access token chỉ hiện khi đã có Mã ứng dụng và Khoá bí mật.
2. Bấm Fetch access token. Facebook hiện màn hình đăng nhập và xin quyền pages_show_list, pages_messaging, pages_manage_metadata. Hãy chọn đúng Page cần kết nối khi Facebook hỏi.
3. Sau khi đồng ý, Facebook chuyển về /oa/{code}/auth-callback. EzyOA thực hiện lần lượt:
   • Đổi code lấy user token ngắn hạn, rồi đổi sang user token dài hạn.
   • Gọi GET /{appUuid}?fields=id,name,access_token bằng user token dài hạn để đổi username/ID của Page sang Page ID và lấy Page Access Token (token của Page lấy từ user token dài hạn không hết hạn).
   • Lưu Page Access Token (vào Khoá bí mật webhook) và Page ID.
   • Đăng ký (subscribe) Page vào app với field messages. Nếu bước này thất bại, EzyOA chỉ ghi log cảnh báo và bạn có thể subscribe thủ công (mục 6).
4. EzyOA chuyển bạn về trang chi tiết dịch vụ.

• Phải là username của Page (phần sau facebook.com/, ví dụ youngmonkeys.org) hoặc Page ID dạng số. Facebook không có API đổi tên hiển thị của Page (ví dụ Young Monkeys) sang ID, nên không dùng được tên có khoảng trắng.
• Page ID được tra lại từ API mỗi lần bấm nút, giá trị lưu lại chỉ để xem.
• Tài khoản dùng để đăng nhập phải có quyền quản trị Page đó.

Cấu hình Webhook trên Facebook

Phải hoàn tất mục 4 (đã lưu và kích hoạt) trước khi làm bước này, vì Facebook gọi vào webhook ngay khi bạn bấm xác minh.

1. Mở app tại <https://developers.facebook.com/apps>,rồi tìm màn hình cấu hình webhook theo một trong các cách sau (tuỳ loại app):
   • Use cases -> use case Messenger -> Customize -> Messenger API settings -> mục Configure webhooks.
   • Messenger -> Settings -> mục Webhooks (app có sản phẩm Messenger kiểu cũ).
   • Webhooks ở menu trái -> chọn đối tượng Page -> Subscribe to this object. Với cách này, đăng ký field messages ngay trong danh sách field của Page.
2. Callback URL: dùng Webhook URL ở trang chi tiết dịch vụ, có dạng https://<web-url>/api/v1/oa/<code>/webhook.
3. Verify token: dán giá trị ở dòng Webhook verify token trên trang chi tiết dịch vụ.
4. Bấm Verify and save. Facebook gửi GET kèm hub.mode=subscribe, hub.verify_token, hub.challenge; EzyOA trả lại hub.challenge nếu token khớp.
5. Ở mục Webhook fields, đăng ký ít nhất trường messages.
6. Nếu log của EzyOA báo can not subscribe page ... to app, vào mục Generate access tokens, thêm Page vào app để Page được subscribe thủ công.

Kiểm tra hoạt động

1. Dùng tài khoản Facebook là admin/developer/tester của app, nhắn tin vào Page.
2. Vào trang admin EzyOA -> danh sách OA Users / tin nhắn: phải thấy người dùng mới cùng tin nhắn vừa gửi (tên và avatar lấy từ Graph API).
3. Trả lời từ admin EzyOA và kiểm tra tin nhắn đã tới Messenger.

Đưa lên chạy thật (Live mode)

• Khi app còn ở Development mode, chỉ admin/developer/tester của app đăng nhập OAuth được và nhắn vào Page được.
• Để nhận tin từ mọi khách hàng, cần chuyển app sang Live mode và xin quyền pages_messaging (Advanced Access) qua App Review. Cần có Privacy Policy URL và thông tin doanh nghiệp đã xác minh theo yêu cầu của Meta.
• EzyOA gửi tin với messaging_type = RESPONSE, nên chỉ trả lời được trong 24 giờ kể từ tin nhắn gần nhất của người dùng. Ngoài khung 24 giờ, Facebook sẽ từ chối.

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

Bảo mật

• App Secret, Page Access Token, Verify Token là thông tin nhạy cảm, không commit vào git và không gửi qua kênh công khai. EzyOA lưu App Secret và Page Access Token dưới dạng password setting (mã hoá).
• Nếu nghi ngờ lộ token: Reset App Secret ở App settings -> Basic, cập nhật lại Khoá bí mật trong EzyOA rồi bấm lại Fetch access token.
• Luôn điền Khoá bí mật (App Secret) ở môi trường production để EzyOA từ chối các request webhook giả mạo.