Hướng dẫn August 5, 2026

Cần xác minh gì sau khi WhatsApp Embedded Signup hoàn tất

Cửa sổ WhatsApp Embedded Signup hoàn tất chỉ chứng minh luồng trình duyệt đã kết thúc. Trước khi đánh dấu tenant sẵn sàng, backend phải đối chiếu kết quả với phiên máy chủ, xác minh token, chọn đúng WhatsApp Business Account (WABA), kiểm tra quyền system user và trạng thái số, đăng ký app với WABA, rồi chứng minh một webhook thật đã đến đúng tenant. Mỗi bước phải là một cổng nghiệm thu riêng.

Điểm chính

FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING cho biết cửa sổ Coexistence đã hoàn tất, không chứng minh mọi bước backend thành công.
Collection chính thức của Meta yêu cầu lấy WABA được chia sẻ, quản lý system user, đăng ký số khi phù hợp và đăng ký webhook cho WABA.
Không lấy WABA đầu tiên trong danh sách; phải khớp chính xác với business và tenant hiện tại.
Gắn credit line chỉ cần cho mô hình partner-paid, không phải điều kiện chung.
Tín hiệu sẵn sàng cuối cùng là webhook thật đi qua tenant routing, validation, deduplication và acknowledgement.

Embedded Signup collection chính thức của Meta tách luồng trình duyệt khỏi công việc Graph API: lấy WABA được chia sẻ, thêm hoặc xác minh system user, đăng ký số, đăng ký app và chia sẻ credit line khi đối tác chịu trách nhiệm thanh toán.

Phạm vi này khác với checklist chuyển sang Embedded Signup v4, vốn tập trung vào cấu hình khởi chạy và duy trì Coexistence. Bài này bắt đầu sau finish event và xác định bằng chứng cần có trước khi hiển thị “Đã kết nối”.

Cổng	Bằng chứng cần lưu	Ranh giới lỗi
Phiên	tenant ID, state dùng một lần, configuration ID, thời gian	Kết quả có thể gắn nhầm tenant
Token	app, scopes, thời hạn	có token nhưng không quản lý được WABA
WABA	WABA ID đúng business context	phần tử đầu có thể thuộc khách hàng khác
System user	ID và task cần thiết	cửa sổ xong nhưng Graph API thất bại
Số điện thoại	phone-number ID và trạng thái registration/Coexistence	asset có nhưng messaging chưa sẵn sàng
App subscription	WABA xuất hiện trong `subscribed_apps`	Meta nhận tin nhưng webhook không đến
Delivery	event, tenant routing, validation, response	có cấu hình nhưng không có bằng chứng E2E

Thực hiện theo đúng thứ tự

1. Đối chiếu kết quả với phiên máy chủ

Trước khi mở cửa sổ Meta, máy chủ tạo một phiên dùng một lần, lưu tenant, người thao tác, configuration ID và loại onboarding. Chỉ chấp nhận kết quả một lần; từ chối state hết hạn hoặc không khớp. Không đưa token vào browser log, analytics hay báo cáo lỗi.

Với Coexistence, ghi nhận event chính thức FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING. Với luồng Embedded Signup khác, dùng contract hiện tại của luồng đó thay vì chỉ dựa vào nhãn hiển thị hoặc một số version.

2. Xác minh token trước asset ID

Dùng token debugging của Meta để xác nhận token thuộc app và có quyền cần thiết. Token không rỗng chưa phải bằng chứng ủy quyền. Chỉ lưu metadata tối thiểu cho audit và renewal ở server; không ghi token gốc vào log.

3. Chọn WABA một cách xác định

Lấy shared/client WABA mà business có thể truy cập, rồi khớp WABA ID với context của phiên hiện tại. Hệ thống multi-tenant không được phụ thuộc thứ tự mảng. Nếu không có kết quả chính xác, giữ trạng thái verification_required thay vì tự động gắn asset khác.

4. Kiểm tra system user và đường đi của số

Collection chính thức dùng GET /{waba-id}/assigned_users để kiểm tra system user; đồng thời xác nhận task backend cần. Cloud API chuẩn có thể cần đăng ký số. Coexistence dùng số đã kết nối với WhatsApp Business app, vì vậy hãy xác minh trạng thái hiện tại thay vì đăng ký lại. Hướng dẫn quyết định Coexistence giúp xác định khi nào mô hình chính thức này thật sự cần thiết.

5. Đăng ký WABA và chứng minh delivery

Gọi POST /{waba-id}/subscribed_apps bằng credentials phía server, sau đó đọc lại trạng thái. Tách trạng thái subscription khỏi phone readiness vì mỗi phần có thể thành công hoặc thất bại riêng.

Cuối cùng, dùng một tin nhắn kiểm thử có kiểm soát và yêu cầu webhook thật đi qua tenant lookup, payload validation, deduplication và acknowledgement. Với UnifyPort, làm theo webhook delivery và xác minh chữ ký: kiểm tra raw body, X-Device-Timestamp, X-Device-Signature và signing_secret của endpoint.

UnifyPort phù hợp ở đâu

UnifyPort không hoàn tất Meta Embedded Signup, cấp quyền WABA, đăng ký số Cloud API, gắn credit line hoặc duy trì Coexistence. Solution Partner hoặc Tech Provider cần các asset này nên dùng luồng chính thức.

UnifyPort giải quyết phạm vi hẹp hơn: kết nối tài khoản WhatsApp thông thường và chuẩn hóa tin nhắn đến được hỗ trợ thành message.received. Nếu mục tiêu là inbound queue thay vì provisioning WABA khách hàng, hãy so sánh ba đường đi WhatsApp inbound rồi xem hướng dẫn xác thực WhatsApp.

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

Checklist này không chứng minh business eligibility, App Review, display name, chất lượng số hay compliance của Meta; đó là các trạng thái riêng. Một tenant thử nghiệm thành công cũng không chứng minh mọi cấu hình khách hàng sẽ hoạt động.

Giao diện không chính thức không thể cấp Cloud API asset và không thay Embedded Signup cho SaaS multi-tenant. Ngược lại, cửa sổ hoàn tất không chứng minh tenant mapping, retry, webhook receiver hoặc billing boundary đúng. Hãy tách “browser complete” và “operational ready” thành hai trạng thái.

FAQ

`FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING` nghĩa là gì?

Cửa sổ WhatsApp Business app onboarding đã đạt finish state chính thức. Backend vẫn phải kiểm tra session, asset, quyền, subscription và delivery.

Chưa. Cần xác minh token, đúng WABA, system user, đường đi của số và webhook subscription.

Mọi tích hợp đều cần credit line?

Không. Chỉ mô hình đối tác trả Meta rồi tính phí khách hàng mới cần bước tương ứng.

Có đăng ký lại số Coexistence không?

Không. Hãy kiểm tra trạng thái và đồng bộ chính thức thay vì lặp lại đăng ký số chuẩn.

Tín hiệu nghiệm thu cuối cùng là gì?

Ít nhất một webhook kiểm thử phải đến đúng tenant và được receiver gần production xác minh, phản hồi.

Bước tiếp theo

Triển khai các cổng theo collection chính thức của Meta trước khi kích hoạt tenant. Nếu chỉ cần inbound tài khoản thường, hãy đánh giá xác thực WhatsApp của UnifyPort.

Nguồn

Nguồn chính thức được kiểm tra ngày 2026-08-05: