Hướng dẫn July 16, 2026

Di chuyển WhatsApp Embedded Signup v4: Checklist Coexistence trước ngày 15/10/2026

Nếu integration của bạn onboarding số WhatsApp Business app hiện có thông qua Coexistence, hãy di chuyển Embedded Signup v2 sang v4 trước ngày 15/10/2026. Meta yêu cầu một cấu hình Facebook Login for Business mới cho v4; việc chọn Embedded Signup và các sản phẩm cần thiết sẽ chuyển flow sang v4. Đây là một đợt di chuyển onboarding, không phải thay đổi giao diện mang tính hình thức: hãy kiểm thử lại permissions, callbacks, lựa chọn Coexistence, webhooks và đồng bộ lịch sử.

Điểm chính

Meta cho biết Embedded Signup v2 sẽ bị ngừng vào ngày 15/10/2026 và khuyến nghị chuyển sang v4 trước thời điểm đó để tránh gián đoạn.
V4 được thiết lập bằng một cấu hình Facebook Login for Business mới. Việc chọn sản phẩm quyết định assets và permissions được đưa vào flow.
Onboarding người dùng WhatsApp Business app — flow thường được gọi là Coexistence — vẫn được hỗ trợ trong v4.
Một đợt di chuyển thành công phải chứng minh nhiều hơn việc “hộp thoại mở được”: cần xác minh lựa chọn Coexistence, finish callback, asset IDs, token exchange, webhook delivery và cửa sổ đồng bộ lịch sử 24 giờ.
Những đội không cần Business app chính thức và Cloud API dùng chung một số nên xác định Coexistence có thực sự cần thiết hay không trước khi đầu tư vào việc di chuyển.

Tài liệu v4 của Meta cho biết v4 được phát hành ngày 08/10/2025 và hiện thay thế v2 để trở thành hướng triển khai Embedded Signup hiện tại. Thay đổi quan trọng nhất nằm ở nơi flow được định nghĩa.

Trong v2, các lựa chọn quan trọng của flow nằm trong object extras do integration truyền vào. Với v4, Meta hướng dẫn developer tạo một cấu hình Facebook Login for Business mới, chọn Embedded Signup làm login variation và chọn các sản phẩm cần có trong flow. Các sản phẩm được chọn sẽ tự động xác định v4 và chọn trước assets cùng permissions bắt buộc.

Điều đó làm thay đổi phạm vi cần kiểm tra khi di chuyển:

Hạng mục di chuyển	Cần xác minh trong v4	Vì sao quan trọng
Login configuration	Một cấu hình Facebook Login for Business mới sử dụng variation Embedded Signup	Dùng lại cấu hình v2 cũ không phải hướng v4 được tài liệu quy định
Products	Cloud API và mọi messaging products bổ sung đều được chọn có chủ đích	Việc chọn sản phẩm quyết định trải nghiệm onboarding và assets bắt buộc
Permissions	Mọi permission được chọn tự động đều có Advanced Access	Hộp thoại trông đúng vẫn có thể thất bại nếu app thiếu quyền truy cập
Coexistence	Flow cho phép kết nối WhatsApp Business app account và number hiện có	Flow Cloud API mặc định không chứng minh onboarding Business app vẫn hoạt động sau khi di chuyển
Session result	Finish event, asset IDs và exchangeable token code được trả về spawning window	Backend vẫn cần kết quả này để hoàn tất onboarding
Webhooks	Payloads về history, state sync và message echoes đều được tiếp nhận	Coexistence phụ thuộc vào đồng bộ sau signup, không chỉ riêng bước signup

V4 cũng hợp nhất việc chọn assets, business information và permissions, đồng thời có thể bao gồm các sản phẩm như Click to WhatsApp Ads và Conversions API. Những phần bổ sung này không bắt buộc nếu bạn chỉ di chuyển Coexistence. Chỉ chọn các sản phẩm mà integration thực sự hỗ trợ; hộp thoại rộng hơn sẽ kéo theo nhiều permissions và công việc kiểm thử hơn.

Có. Hướng dẫn onboarding Business app đã cập nhật của Meta nêu rõ onboarding người dùng WhatsApp Business app vẫn được hỗ trợ. Hướng dẫn này gọi tính năng đó là “Coexistence” trong tài liệu hỗ trợ và tài liệu dành cho partner.

Cần đọc các trang chính thức cùng nhau. Hướng dẫn chung về các phiên bản hiển thị một object extras được để trống có chủ đích cho v4, trong khi hướng dẫn Coexistence chuyên biệt vẫn mô tả lựa chọn feature whatsapp_business_app_onboarding và một phiên bản session info. Đừng cho rằng việc xóa mọi thiết lập dành riêng cho Coexistence khỏi launcher hiện tại sẽ giữ nguyên flow. Hãy tạo cấu hình v4 mới, làm theo hướng dẫn onboarding Business app hiện hành và xác minh màn hình cùng callback thực tế bằng test account.

Hành trình người dùng dự kiến rất cụ thể: doanh nghiệp chọn kết nối một WhatsApp Business app account hiện có, nhập số đang sử dụng, xác nhận kết nối bên trong Business app rồi hoàn tất Embedded Signup. Sau đó, Business app vẫn có thể xử lý tin nhắn one-to-one, còn tin nhắn Cloud API và phần lịch sử được hỗ trợ sẽ được đồng bộ.

Nếu đội của bạn vẫn đang cân nhắc có cần workflow hai bề mặt này hay không, hãy đọc hướng dẫn ra quyết định về WhatsApp Coexistence trước. Việc di chuyển chỉ đáng làm khi người dùng thực sự cần Business app và integration Cloud API chính thức trên cùng một số.

Checklist di chuyển Coexistence

1. Kiểm kê mọi entry point của v2

Tìm tất cả button ở production và staging, SDK call, configuration ID, callback handler và feature flag có thể khởi chạy Embedded Signup. Ghi lại phân khúc khách hàng nào dùng Coexistence và phân khúc nào dùng flow Cloud API mặc định. Một launcher dùng chung có thể che giấu lỗi hồi quy Coexistence cho đến khi người dùng Business app thật sự gặp phải.

2. Tạo cấu hình v4 mới

Trong App Dashboard → Facebook Login for Business → Configurations, hãy tạo cấu hình, chọn Embedded Signup, chọn các sản phẩm cần thiết rồi sao chép configuration ID mới vào integration. Meta cho biết việc chọn sản phẩm sẽ đặt experience thành v4.

Kiểm tra assets và permissions được chọn tự động. Với Cloud API, bảng v4 liệt kê WhatsApp Business accounts cùng whatsapp_business_management và whatsapp_business_messaging; cả hai đều yêu cầu Advanced Access.

3. Bật lại và kiểm thử đường đi Coexistence

Sử dụng hướng dẫn onboarding Business app hiện hành của Meta cho flow chuyên biệt. Trong lần chạy thử, hãy xác nhận màn hình chọn WABA-only cũ đã được thay bằng lựa chọn kết nối một WhatsApp Business account hiện có. Nếu lựa chọn đó không xuất hiện, hãy dừng rollout vì bạn đang kiểm thử một onboarding intent khác.

Đồng thời xác nhận các prerequisites được tài liệu nêu rõ: khách hàng dùng WhatsApp Business app 2.24.17 trở lên, tổ chức của bạn là Solution Partner hoặc Tech Provider, callback xử lý được các webhooks bắt buộc và session logging đã bật.

4. Xác minh finish callback và trạng thái onboarding

Hướng dẫn Coexistence mô tả finish event là FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING. Hãy lưu WABA ID, asset IDs và exchangeable token code được trả về, sau đó hoàn tất các bước onboarding khách hàng thông thường nhưng bỏ qua đăng ký phone number vì số này đã được đăng ký.

Đừng nhầm version: 3 được tài liệu ghi trong session payload với phiên bản cấu hình Embedded Signup. Hãy xem chúng là hai contract riêng biệt và assert cả hai trong test thay vì định tuyến chỉ dựa vào một field dạng số.

Sau onboarding, hãy truy vấn các field của business phone number mà Meta quy định cho bước kiểm tra này. Trạng thái kỳ vọng là is_on_biz_app: true cùng platform_type: "CLOUD_API".

5. Chứng minh cả ba đường đồng bộ đều hoạt động

Trước khi launch, hãy subscribe app vào các field WABA webhook bổ sung mà Coexistence yêu cầu:

history cho các tin nhắn trước đây mà khách hàng đã chọn chia sẻ;
smb_app_state_sync cho contact hiện tại và đã thay đổi;
smb_message_echoes cho tin nhắn mới được gửi từ WhatsApp Business app.

Meta cho partner 24 giờ sau onboarding để khởi tạo đồng bộ contact và lịch sử tin nhắn. Mỗi lần khởi tạo chỉ được thực hiện một lần; muốn làm lại, khách hàng phải offboard và hoàn tất flow một lần nữa. Hãy lưu request_id được trả về, tiếp nhận nhanh các webhook batch lớn và xử lý chúng bất đồng bộ.

6. Rollout với ranh giới rollback thực sự

Trong lúc Meta vẫn cho phép cả hai phiên bản, hãy chạy song song cấu hình v2 và v4 cho một cohort được kiểm soát. Theo dõi riêng theo configuration ID các chỉ số completion rate, callback receipt, token exchange, is_on_biz_app, synchronization completion và webhook errors. Nếu v4 không vượt qua một gate, hãy rollback entry point chứ không rollback trạng thái khách hàng đã hoàn tất.

Thời hạn tháng 10 vẫn đủ để tránh một đợt cutover đồng loạt vào phút cuối đầy rủi ro. Hãy hoàn tất di chuyển kỹ thuật trước, rồi xem kế hoạch đo lường phí service message WhatsApp riêng để thay đổi onboarding và pricing không bị gộp vào cùng một release.

UnifyPort phù hợp ở đâu

UnifyPort không di chuyển cấu hình Meta, cấp permissions Cloud API, đồng bộ lịch sử Business app chính thức hay duy trì trạng thái Coexistence của Meta. Nếu sản phẩm cần các khả năng chính thức đó, v4 là hướng đúng và chủ sở hữu integration bắt buộc phải thực hiện việc di chuyển.

UnifyPort phù hợp với một yêu cầu khác: kết nối WhatsApp account thông thường và nhận các tin nhắn inbound được hỗ trợ dưới dạng sự kiện webhook chuẩn message.received. Authorization WhatsApp hỗ trợ ghép nối bằng QR code và phone number; webhook delivery có chữ ký sử dụng X-Device-Timestamp, X-Device-Signature và signing_secret của endpoint.

Lựa chọn thay thế này phù hợp khi mục tiêu thực sự là một inbound queue chứ không phải một số dùng chung cho Business app và Cloud API. Hãy so sánh ba hướng trong hướng dẫn các cách nhận WhatsApp inbound trước khi dành thời gian kỹ thuật cho một đợt di chuyển có các tính năng chính thức mà bạn có thể không cần.

Giới hạn và đánh đổi

Embedded Signup v4 là câu trả lời đúng cho Solution Partners và Tech Providers onboarding khách hàng vào các sản phẩm Cloud API chính thức. Đây cũng là con đường duy nhất trong phần so sánh này duy trì hành vi Coexistence được Meta hỗ trợ, flow chia sẻ lịch sử, mô hình asset chính thức và permissions của sản phẩm Cloud API.

Một giao diện không chính thức không thể cung cấp các đặc quyền đó. Nó cũng không thể giúp doanh nghiệp đủ điều kiện dùng sản phẩm Meta, thay thế customer-service windows của Meta hay biến kết nối account thông thường thành Cloud API WABA. Lợi ích hẹp hơn của nó là một giao diện inbound chuẩn mà không yêu cầu khách hàng dùng toàn bộ stack Coexistence chính thức.

Việc di chuyển v4 cũng không loại bỏ các giới hạn vận hành mà Meta quy định cho Coexistence. Meta hiện liệt kê throughput cố định 20 messages per second cho số dùng đồng thời trên Business app và Cloud API, pricing Cloud API riêng cho tin nhắn gửi qua API, không hỗ trợ đồng bộ lịch sử nhóm và các giới hạn cụ thể với companion devices. Hãy kiểm tra lại các ràng buộc này theo hướng dẫn chính thức trong acceptance testing.

FAQ

Meta cho biết Embedded Signup v2 sẽ bị ngừng vào ngày 15/10/2026. Chủ sở hữu integration nên chuyển sang v4 trước thời điểm đó để tránh gián đoạn onboarding.

Mọi người dùng WhatsApp Business app đều phải di chuyển sao?

Không. Việc di chuyển thuộc trách nhiệm của partner hoặc provider sở hữu integration Embedded Signup v2. Doanh nghiệp chỉ dùng WhatsApp Business app độc lập không duy trì cấu hình Embedded Signup.

V4 có loại bỏ WhatsApp Coexistence không?

Không. Meta cho biết onboarding người dùng WhatsApp Business app tiếp tục được hỗ trợ trong v4. Quá trình di chuyển phải giữ lại và kiểm thử lựa chọn Coexistence chuyên biệt thay vì cho rằng flow Cloud API mặc định là tương đương.

Có. Hướng dẫn v4 của Meta yêu cầu developer tạo một cấu hình mới, chọn Embedded Signup làm login variation và chọn các sản phẩm cần đưa vào.

Một bài test di chuyển cần chứng minh điều gì?

Tối thiểu phải chứng minh: lựa chọn kết nối Business app hiện có xuất hiện; finish callback và assets được trả về; token exchange hoàn tất; is_on_biz_app là true với platform_type đặt thành CLOUD_API; và các đường webhook history, smb_app_state_sync, smb_message_echoes đều hoạt động.

Bước tiếp theo

Nếu bạn sở hữu integration Meta Embedded Signup, hãy tạo cấu hình mới theo hướng dẫn di chuyển v4 chính thức và chạy checklist trên trong staging. Nếu bạn chỉ cần inbound messaging cho account thông thường, hãy dùng hướng dẫn authorization WhatsApp của UnifyPort để đánh giá hướng riêng đó trước khi xây dựng Coexistence.

Nguồn

Các nguồn chính thức của Meta được kiểm tra ngày 16/07/2026: