Cấu hình WhatsApp Embedded Signup

Tích hợp giải pháp đăng ký nhúng (WhatsApp Embedded Signup) của Meta lên portal giúp khách hàng của bạn có thể tự kết nối tài khoản WhatsApp Business của họ bằng quy trình hướng dẫn từng bước trực quan ngay trên trình duyệt.

Đ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.

Create App button in the Facebook Developer Portal

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.

Chọn trường hợp sử dụng (Use case)

Khi hệ thống yêu cầu chọn trường hợp sử dụng, tích chọn Other.

Use case selection - Other option highlighted

Chọn loại ứng dụng (App type)

Chọn loại ứng dụng là Business.

App type selection - Business option highlighted

Hoàn tất khởi tạo

Kiểm tra lại thông tin và nhấn Create App để hoàn tất quá trình tạo ứng dụng.

Confirmation screen before creating the app

Lấy thông tin App ID và App Secret

Sau khi tạo ứng dụng thành công, đi đến mục Settings → Basic để lấy App ID và App Secret. Nhấn nút Show và nhập mật khẩu Facebook để hiển thị App Secret. Bạn sẽ cần hai giá trị này ở bước tiếp theo.

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.

Mở trang cấu hình kết nối

Đăng nhập vào Portal quản trị của bạn, truy cập mục:

https://app.chatconnectx.com/manage/integrations

Sau đó chọn WhatsApp.

chatbotx_super_admin_integrations_whatsapp

Mở cấu hình WhatsApp

Tìm thẻ cấu hình WhatsApp và nhấn nút Edit để mở cửa sổ cấu hình.

chatbotx_super_admin_whatsapp_edit_modal

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`

Mã Client ID và Client Secret phải khớp hoàn toàn với ứng dụng Facebook của bạn. Nếu nhập sai, quy trình đăng ký Embedded Signup sẽ báo lỗi hoặc không thể hoàn tất.

Lưu cấu hình

Nhấn Save để lưu cài đặt. Thẻ WhatsApp lúc này sẽ hiển thị thông tin Client ID và tên doanh nghiệp của bạn. Cổng kết nối WhatsApp Embedded Signup đã được kích hoạt.

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.

Nếu có thông báo cảnh báo “Missing valid payment method” (Thiếu phương thức thanh toán), hãy nhấn Add payment method để thiết lập thông tin thanh toán cho tài khoản doanh nghiệp Meta của bạn. Nếu thiếu bước này, bạn sẽ không thể gửi tin nhắn ra ngoài môi trường thử nghiệm (free test tier).

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.

Nếu ứng dụng của bạn đã được thêm sản phẩm này trước đó (ví dụ: khi cấu hình Messenger hoặc Instagram), bạn có thể bỏ qua bước này và đi đến Bước 4.

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.

Facebook Login For Business Configuration Menu

Đặt tên cấu hình

Nhập tên gợi nhớ cho cấu hình (ví dụ: ChatconnectX), sau đó nhấn Next.

Chọn kiểu Login (Login variation)

Chọn kiểu đăng nhập là WhatsApp Embedded Signup, sau đó nhấn Next.

Facebook Create Configuration Step Login Variation

Cài đặt này không thể thay đổi sau khi tạo. Đảm bảo bạn đã chọn chính xác WhatsApp Embedded Signup trước khi tiếp tục.

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.

Facebook Create Configuration Step Products

Cài đặt này không thể thay đổi sau khi tạo. Đảm bảo bạn đã tích chọn sản phẩm WhatsApp Cloud API trước khi tiếp tục.

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.

Facebook Create Configuration Step Access Token

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.

Facebook Create Configuration Step Assets

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

Facebook Create Configuration Step Permissions

Nhấn Create để hoàn tất khởi tạo.

Sao chép mã Configuration ID

Màn hình thành công sẽ hiển thị. Hãy sao chép mã Configuration ID được hiển thị để điền vào biểu mẫu cấu hình tại Bước 2.

Facebook Configuration Id Generated Copy

Trước khi ghi đè đường dẫn Callback URL, ứng dụng Facebook của bạn phải được đăng ký nhận sự kiện tin nhắn cho WhatsApp Business Account nhằm tránh gặp lỗi (#100) khi cấu hình webhook. Đảm bảo trường webhook messages đã được đăng ký (Subscribed) tại phần cấu hình Webhooks của sản phẩm WhatsApp trên ứng dụng Facebook.

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

Nhấn Generate Token. Hãy sao chép mã token hiển thị trên màn hình, đây chính là System User Token bạn cần nhập ở Bước 2.

Sao chép và lưu trữ mã này ngay lập tức. Sau khi đóng cửa sổ thông báo, bạn sẽ không thể xem lại mã token này.

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.

{
  "name": "Tên System User của bạn",
  "id": "110835055179851"
}

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

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/integrations chưa.

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 messages của tài khoản WhatsApp Business.
Tiến hành chạy lại luồng 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ướ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

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?

Kiểm tra Logs máy chủ: Xem lịch sử lỗi trong log dịch vụ của cả rails và 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.

Tài liệu tham khảo

Để biết thêm thông tin chi tiết về mặt kỹ thuật, bạn có thể tham khảo tài liệu chính thức từ Meta: WhatsApp Embedded Signup - Meta for Developers.

Platform

SaaS

Channels

Điều kiện chuẩn bị

Bước 1: Tạo ứng dụng Facebook (Facebook App)

Bước 2: Cấu hình Credentials trên Portal quản trị

Bước 3: Cấu hình sản phẩm WhatsApp trên ứng dụng Facebook

Bước 4: Lấy mã Configuration ID

Bước 5: Tạo System User ID và Access Token

Hướng dẫn kết nối cho người dùng

Tuân thủ chính sách thương mại (Commerce Policy)

Xử lý sự cố thường gặp

Tài liệu tham khảo

​Điều kiện chuẩn bị

​Bước 1: Tạo ứng dụng Facebook (Facebook App)

​Bước 2: Cấu hình Credentials trên Portal quản trị

​Bước 3: Cấu hình sản phẩm WhatsApp trên ứng dụng Facebook

​Bước 4: Lấy mã Configuration ID

​Bước 5: Tạo System User ID và Access Token

​Hướng dẫn kết nối cho người dùng

​Tuân thủ chính sách thương mại (Commerce Policy)

​Xử lý sự cố thường gặp

​Tài liệu tham khảo

Điều kiện chuẩn bị

Bước 1: Tạo ứng dụng Facebook (Facebook App)

Bước 2: Cấu hình Credentials trên Portal quản trị

Bước 3: Cấu hình sản phẩm WhatsApp trên ứng dụng Facebook

Bước 4: Lấy mã Configuration ID

Bước 5: Tạo System User ID và Access Token

Hướng dẫn kết nối cho người dùng

Tuân thủ chính sách thương mại (Commerce Policy)

Xử lý sự cố thường gặp

Tài liệu tham khảo