Điều kiện chuẩn bị
Trước khi bắt đầu, hãy đảm bảo bạn có:- Một tài khoản Facebook cá nhân hoạt động bình thường.
- Một tài khoản WhatsApp Business (hoặc khả năng đăng ký khởi tạo tài khoản mới trong quá trình thiết lập).
- Một portal được cấu hình tên miền riêng chạy giao thức bảo mật HTTPS và truy cập được công khai.
- Quyền quản trị cao nhất (Super Admin) trên Portal của bạn để nhập cấu hình.
Nếu bạn đang phát triển thử nghiệm ở môi trường cục bộ (local), bạn sẽ cần công cụ tạo đường hầm như ngrok để public server của mình ra internet nhằm nhận webhook từ Facebook.
Bước 1: Tạo ứng dụng Facebook (Facebook App)
Nếu bạn đã có ứng dụng Facebook (ví dụ: từ phần cấu hình kênh Messenger), bạn có thể tái sử dụng ứng dụng đó và chuyển nhanh tới Bước 2.Khởi tạo ứng dụng mới
Truy cập vào trang quản trị Facebook Developer Portal và nhấn Create App.
Nhập thông tin ứng dụng
Nhập tên ứng dụng hiển thị (App name) và email liên hệ (contact email), sau đó nhấn Next.
Bước 2: Cấu hình Credentials trên Portal quản trị
Bạn cần nhập thông tin ứng dụng Facebook và WhatsApp vào Portal quản trị dưới tư cách Super Admin trước khi tích hợp có thể hoạt động.
Nhập thông tin Credentials
Tại cửa sổ Edit WhatsApp, điền đầy đủ thông tin vào các trường:
| Trường | Mô tả | Nơi lấy thông tin | Ví dụ |
|---|---|---|---|
| Client ID | Mã ID ứng dụng Facebook | Meta Developer Portal → Ứng dụng → Settings → Basic | 1974877133429651 |
| Client Secret | Mã khóa bảo mật của ứng dụng | Cùng trang cơ bản → nhấn Show | ●●●●●●●●●● |
| API Version | Phiên bản API của Graph API | Ứng dụng → Settings → Advanced → API Version | v20.0 |
| Webhook Verify Token | Chuỗi ký tự bảo mật xác thực webhook | Bạn tự tạo một chuỗi ngẫu nhiên (chữ và số) | i7CTHYSF66uEHS3B |
| App Config ID | Mã ID cấu hình từ trình tạo Facebook Login | Facebook Login for Business → Configurations. Xem hướng dẫn tại Bước 4 | 783655134328535 |
| System User ID | Mã ID của System User, lấy qua Graph API Explorer | Graph API Explorer. Xem hướng dẫn tại Bước 5 | 110835055179851 |
| System User Token | Mã Access token vô hạn của System User | Meta Business Settings. Xem hướng dẫn tại Bước 5 | EAACanps... |
| Business ID*(tùy chọn)* | Mã Portfolio doanh nghiệp của bạn | Meta Business Settings → Business Info | 627055339164xxx |
| Business Name | Tên doanh nghiệp hiển thị trên hệ thống | Nhập tên thương hiệu của bạn | chatconnectx |
Bước 3: Cấu hình sản phẩm WhatsApp trên ứng dụng Facebook
Thêm sản phẩm WhatsApp
Tại trang quản trị ứng dụng Facebook của bạn, chọn mục Add Product ở menu bên trái. Tìm sản phẩm WhatsApp và nhấn Set Up.
Xác nhận trang tổng quan WhatsApp Quickstart
Hệ thống sẽ chuyển hướng bạn đến giao diện WhatsApp Quickstart. Điều này xác nhận sản phẩm WhatsApp đã được thêm vào ứng dụng thành công.
KHÔNG nhấn vào nút “Start using the API!”. Nút này dùng để thiết lập Cloud API trực tiếp theo phương thức thủ công. Hệ thống của bạn sử dụng luồng Embedded Signup để tự động cấu hình toàn bộ quy trình, nên bạn có thể bỏ qua phần thiết lập thủ công đó.
Thêm sản phẩm Facebook Login for Business
Đăng ký Embedded Signup yêu cầu ứng dụng phải tích hợp sản phẩm Facebook Login for Business. Quay lại trang Dashboard ứng dụng của bạn, chọn Add Product, tìm sản phẩm Facebook Login for Business và nhấn Settings.
Bước 4: Lấy mã Configuration ID
Mã Configuration ID là khóa cấu hình quan trọng dùng để kích hoạt giao diện đăng ký Embedded Signup của WhatsApp trên portal của bạn. Mã này được tạo từ phần thiết lập Facebook Login for Business.Truy cập mục Cấu hình Facebook Login for Business
Tại menu bên trái ứng dụng Facebook, mở rộng mục Facebook Login for Business và chọn Configurations. Nhấn nút Create configuration để bắt đầu.
Chọn kiểu Login (Login variation)
Chọn kiểu đăng nhập là WhatsApp Embedded Signup, sau đó nhấn Next.
Chọn sản phẩm tích hợp (Products)
Tích chọn sản phẩm WhatsApp Cloud API ở bước này, sau đó nhấn Next.
Cấu hình Token (Access token)
Thiết lập thời hạn hết hạn token (Token expiration) là Never (Không bao giờ hết hạn) để đảm bảo kết nối của người dùng không bị gián đoạn, sau đó nhấn Next.
Cấu hình tài sản (Assets)
Giữ các lựa chọn tài sản mặc định theo hệ thống và nhấn Next. Trình thuật sĩ đã tự động chọn các tài sản cần thiết theo sản phẩm bạn đăng ký ở các bước trước.
Kiểm tra các quyền truy cập (Permissions)
Kiểm tra lại danh sách quyền. Đảm bảo ứng dụng được cấp tối thiểu 3 quyền sau của WhatsApp:
| Quyền | Mục đích sử dụng |
|---|---|
whatsapp_business_management | Đọc và quản lý tài sản WhatsApp Business (số điện thoại, hồ sơ) |
whatsapp_business_messaging | Gửi và nhận tin nhắn, cuộc gọi qua WhatsApp |
whatsapp_business_manage_events | Quản lý các sự kiện của tài khoản WhatsApp |
Bước 5: Tạo System User ID và Access Token
Truy cập mục System Users
Truy cập trang Meta Business Settings, chọn mục Users → System Users ở menu bên trái. Nếu chưa có System User, hãy nhấn Add, đặt tên gợi nhớ và chọn vai trò là Admin.
Tạo mã Access Token mới
Chọn System User vừa tạo, nhấn nút Generate New Token. Cấu hình các thông số sau:
- Select App: Chọn đúng ứng dụng Facebook bạn đã khởi tạo.
- Token Expiration: Chọn Never để tránh gián đoạn kết nối do hết hạn token.
- Select Permissions: Tích chọn 3 quyền truy cập bắt buộc:
| Quyền | Mục đích sử dụng |
|---|---|
business_management | Quản lý thông tin cài đặt và tài sản doanh nghiệp |
whatsapp_business_management | Đọc và quản lý các tài sản WhatsApp Business |
whatsapp_business_messaging | Thực hiện gửi và nhận tin nhắn WhatsApp |
Lấy System User ID qua Graph API Explorer
Truy cập Meta Graph API Explorer, dán mã System User Token vừa tạo vào ô Access Token, cấu hình truy vấn
GET /me và nhấn Submit. Sao chép giá trị id nhận được từ phản hồi JSON, đây chính là System User ID của bạn.Hướng dẫn kết nối cho người dùng
Sau khi hoàn tất cấu hình ứng dụng trên Meta Developer Portal và nhập Credentials vào Portal quản trị, khách hàng của bạn có thể tự kết nối tài khoản WhatsApp Business của họ qua luồng Embedded Signup. Xem chi tiết tại Hướng dẫn kết nối WhatsApp.Tuân thủ chính sách thương mại (Commerce Policy)
Meta sẽ thực hiện đánh giá hồ sơ doanh nghiệp của bạn để đảm bảo tuân thủ đầy đủ Chính sách thương mại của WhatsApp và sẽ gửi thông báo trong vòng 24 giờ nếu có bất kỳ vấn đề nào phát sinh.Xử lý sự cố thường gặp
Không hiển thị nút kết nối WhatsApp Embedded Signup
Không hiển thị nút kết nối WhatsApp Embedded Signup
Lỗi này xảy ra do cấu hình Credentials trên portal quản trị Super Admin chưa đầy đủ hoặc không chính xác.Cách khắc phục:
- Kiểm tra xem Super Admin đã nhập đầy đủ các thông số bắt buộc (App ID, App Secret, Configuration ID) tại đường dẫn
/manage/integrationschưa.
Gặp lỗi (#100) khi cấu hình webhook
Gặp lỗi (#100) khi cấu hình webhook
Ứng dụng Facebook của bạn phải được đăng ký nhận sự kiện tin nhắn trước khi thực hiện thiết lập Callback URL.Các bước sửa lỗi:
- Truy cập trang quản lý ứng dụng trên Meta Developer Portal.
- Chọn WhatsApp → Configuration ở menu bên trái.
- Tại mục Webhooks, nhấn đăng ký (Subscribe) cho trường
messagescủa tài khoản WhatsApp Business. - Tiến hành chạy lại luồng Embedded Signup.
Lỗi xác thực thông tin khi chạy Embedded Signup
Lỗi xác thực thông tin khi chạy Embedded Signup
Checklist kiểm tra:
- Đảm bảo tài khoản Facebook bạn đang đăng nhập để thực hiện kết nối giữ quyền quản trị viên (Admin) đối với Meta Business Portfolio.
- Kiểm tra ứng dụng Facebook đã được cấp đủ 3 quyền:
whatsapp_business_management,whatsapp_business_messaging,whatsapp_business_manage_events. - Xác minh mã App ID và App Secret cấu hình tại trang Portal quản trị khớp hoàn toàn với thông tin ứng dụng trong mục Settings → Basic của Meta Developer Portal.
Hồ sơ xác minh doanh nghiệp hiển thị trạng thái chờ duyệt hoặc bị từ chối
Hồ sơ xác minh doanh nghiệp hiển thị trạng thái chờ duyệt hoặc bị từ chối
Hướng xử lý:
- Kiểm tra lại các thông tin của doanh nghiệp đảm bảo tính chính xác và khớp với giấy tờ pháp lý (tên doanh nghiệp, địa chỉ, trang web chính thức).
- Đảm bảo lĩnh vực kinh doanh của bạn tuân thủ đúng Chính sách thương mại của WhatsApp.
- Trong thời gian chờ xác minh, các tài khoản mới sẽ có một giới hạn gửi tin nhắn tạm thời (messaging limit) nhỏ hơn mức thông thường.
- Quá trình xác minh doanh nghiệp thường diễn ra trong vòng 1 ngày làm việc.
Hồ sơ gửi xét duyệt ứng dụng (App Review) bị từ chối
Hồ sơ gửi xét duyệt ứng dụng (App Review) bị từ chối
Các bước xử lý:
- Mở xem chi tiết hồ sơ bị từ chối tại giao diện Meta Developer Dashboard.
- Đọc kỹ lý do từ chối và phản hồi của đội ngũ kiểm duyệt Meta.
- Bạn có thể sử dụng biểu tượng hỗ trợ của Messenger ở góc dưới bên phải màn hình để liên hệ trao đổi trực tiếp với Meta để được làm rõ.
- Cung cấp đầy đủ các tài liệu hướng dẫn sử dụng, tài khoản thử nghiệm và video ghi lại quá trình thao tác rõ ràng để người kiểm duyệt thực hiện.
- Gửi lại hồ sơ xét duyệt mới sau khi đã điều chỉnh theo phản hồi.
Làm thế nào để nhận hỗ trợ nếu sự cố vẫn chưa được khắc phục?
Làm thế nào để nhận hỗ trợ nếu sự cố vẫn chưa được khắc phục?
- Kiểm tra Logs máy chủ: Xem lịch sử lỗi trong log dịch vụ của cả
railsvàsidekiq. - Kiểm tra trạng thái tài khoản: Đảm bảo tất cả điều kiện ban đầu (xác minh doanh nghiệp, quyền truy cập tài sản, thanh toán hóa đơn) của Meta/WhatsApp đều hoạt động bình thường.
- Liên hệ hỗ trợ cộng đồng: Tham gia gửi câu hỏi tại trang Cộng đồng hỗ trợ ChatbotX kèm theo ảnh chụp lỗi cụ thể của bạn.