チュートリアル July 16, 2026

WhatsApp Embedded Signup v4のCoexistence移行：2026年10月15日までのチェックリスト

既存のWhatsApp Business Appの電話番号をCoexistence経由でonboardingする連携は、2026年10月15日までにEmbedded Signup v2からv4へ移行する必要があります。Metaでは、v4用に新しいFacebook Login for Business configurationが必要です。Embedded Signupと必要な製品を選ぶことで、フローがv4になります。これは単なる画面の更新ではなく、onboardingの移行です。権限、callbacks、Coexistenceの選択肢、webhooks、履歴同期をすべて再テストしてください。

要点

MetaはEmbedded Signup v2を2026年10月15日に廃止すると案内しており、onboardingの中断を避けるため、それまでにv4へ移行するよう推奨しています。
V4は、新しいFacebook Login for Business configurationで設定します。選択した製品によって、フローに含まれるアセットと権限が決まります。
一般にCoexistenceと呼ばれるWhatsApp Business Appユーザーのonboardingは、v4でも引き続きサポートされます。
移行テストでは「ダイアログが開く」だけでは不十分です。Coexistenceの選択肢、finish callback、asset IDs、token exchange、webhook delivery、24時間の履歴同期期限まで確認する必要があります。
公式Business AppとCloud APIで同じ電話番号を共有する必要がないチームは、移行へ投資する前にCoexistenceが本当に必要か判断してください。

Metaのv4ドキュメントによると、v4は2025年10月8日にリリースされ、現在のEmbedded Signupフローとしてv2を置き換えます。実装上の最も重要な変更は、フローを定義する場所です。

V2では、重要なフローの選択肢を連携から渡すextras objectに指定していました。V4では、新しいFacebook Login for Business configurationを作成し、login variationとしてEmbedded Signupを選び、フローへ含める製品を選択するようMetaが案内しています。選択した製品によってv4が自動的に適用され、必要なアセットと権限も事前選択されます。

移行時に確認する範囲は次のとおりです。

移行対象	v4で確認すること	重要な理由
Login configuration	新しく作成したFacebook Login for Business configurationでEmbedded Signup variationを使う	古いv2 configurationの再利用は、v4の正式な手順ではない
Products	Cloud APIと、追加で必要なmessaging productsを意図的に選ぶ	Productの選択によってonboarding体験と必要なアセットが決まる
Permissions	自動選択されたすべてのpermissionにAdvanced Accessがある	ダイアログが正しく見えても、appにpermission accessがなければ失敗する
Coexistence	既存のWhatsApp Business App accountと電話番号を接続する選択肢が表示される	デフォルトのCloud APIフローだけでは、Business App onboardingが維持されたことを証明できない
Session result	Finish event、asset IDs、交換可能なtoken codeが起動元windowへ届く	Backendはonboardingを完了するためにこの結果を必要とする
Webhooks	History、state-sync、message-echoのpayloadを受信できる	Coexistenceはsignupだけでなく、完了後の同期に依存する

V4ではasset selection、business information、permissionsも統合され、Click to WhatsApp AdsやConversions APIなどの製品を含めることもできます。Coexistenceだけを移行する場合、これらは任意です。連携が実際にサポートする製品だけを選んでください。ダイアログの範囲を広げるほど、permissionとテストの作業も増えます。

利用できます。Metaが更新したBusiness App onboardingガイドでは、WhatsApp Business Appユーザーのonboardingが引き続きサポートされると明記されています。サポート資料やpartner向け資料では、この機能を「Coexistence」と呼んでいます。

公式ページは組み合わせて読む必要があります。一般向けのversionsガイドでは、v4用のextras objectが意図的に空になっています。一方、Coexistence専用ガイドには、引き続きwhatsapp_business_app_onboarding feature selectionとsession-info versionが記載されています。既存launcherからCoexistence固有の設定をすべて削除しても同じフローが維持される、と決めつけないでください。新しいv4 configurationを作成し、現行のBusiness App onboarding手順に従い、テストaccountで実際の画面とcallbackを確認します。

想定されるユーザーフローは明確です。企業は既存のWhatsApp Business App accountを接続する選択肢を選び、現在の電話番号を入力し、Business App内で接続を承認してEmbedded Signupを完了します。その後もBusiness Appで1対1のメッセージを扱いながら、Cloud APIのメッセージと対応する履歴を同期できます。

この2つの操作画面が必要かまだ判断できていない場合は、先に既存のWhatsApp Coexistence判断ガイドを確認してください。Business Appと公式Cloud API integrationを同じ電話番号で本当に使う場合に限り、この移行に取り組む価値があります。

Coexistence移行チェックリスト

1. すべてのv2 entry pointを洗い出す

Embedded Signupを起動できるproductionとstagingのbutton、SDK call、configuration ID、callback handler、feature flagをすべて確認します。どの顧客セグメントがCoexistenceを使い、どのセグメントがデフォルトのCloud APIフローを使うか記録してください。起動処理を共用していると、実際のBusiness Appユーザーが操作するまでCoexistenceの不具合に気付かない場合があります。

2. 新しいv4 configurationを作成する

App Dashboard → Facebook Login for Business → Configurationsでconfigurationを作成し、Embedded Signupと必要な製品を選択して、新しいconfiguration IDを連携へ設定します。Metaによると、製品を選択することで体験がv4に設定されます。

自動選択されたassetsとpermissionsを確認します。Cloud APIについて、v4の表にはWhatsApp Business accounts、whatsapp_business_management、whatsapp_business_messagingが掲載されています。2つのpermissionには、どちらもAdvanced Accessが必要です。

3. Coexistenceフローを再び有効化してテストする

専用フローには、Metaの現行Business App onboarding手順を使います。テストでは、従来のWABAだけを選ぶ画面が、既存のWhatsApp Business accountへ接続する選択肢に置き換わっていることを確認してください。この選択肢がなければrolloutを止めます。別のonboarding intentをテストしているためです。

ドキュメントに記載された前提条件も確認します。顧客がWhatsApp Business App 2.24.17以降を利用していること、自社がSolution PartnerまたはTech Providerであること、callbackが必要なwebhooksを処理できること、session loggingが有効であることが必要です。

4. Finish callbackとonboarding状態を確認する

Coexistenceガイドでは、finish eventをFINISH_WHATSAPP_BUSINESS_APP_ONBOARDINGと定義しています。返されたWABA ID、asset IDs、交換可能なtoken codeを取得し、通常の顧客onboarding手順を完了します。電話番号はすでに登録済みなので、phone-number registrationは行いません。

Session payloadに記載されたversion: 3と、Embedded Signup configuration versionを混同しないでください。別々の仕様として両方をテストし、1つの数値だけでroutingしないようにします。

Onboarding後、この確認用にMetaが案内するbusiness phone number fieldsを照会します。期待する状態はis_on_biz_app: true、platform_type: "CLOUD_API"です。

5. 3つの同期経路をすべて確認する

リリース前に、Coexistenceで追加指定されているWABA webhook fieldsをappでsubscribeします。

history：顧客が共有を選んだ過去のメッセージを受信する。
smb_app_state_sync：現在の連絡先と、その後の変更を受信する。
smb_message_echoes：WhatsApp Business Appから新しく送信されたメッセージを受信する。

Metaはpartnerに対し、onboardingから24時間以内に連絡先とmessage-history synchronizationを開始するよう求めています。それぞれの開始処理を実行できるのは1回だけです。再実行するには顧客がoffboardし、もう一度フローを完了する必要があります。返されたrequest_idを保存し、大きなwebhook batchesにはすぐ応答して、処理は非同期で行います。

6. Rolloutに実効性のあるrollback境界を設ける

Metaが両方を許可している間は、限定した対象群でv2とv4のconfigurationを並行稼働させます。完了率、callback receipt、token exchange、is_on_biz_app、同期完了、webhook errorsをconfiguration ID別に追跡してください。V4が判定条件を満たさない場合は、完了済みの顧客状態ではなくentry pointをrollbackします。

10月の期限が近づいているため、直前に一括で切り替える必要はありません。まず技術移行を完了し、その後で別のWhatsApp service message計測プランを確認します。Onboardingと価格変更を同じリリースにまとめないでください。

UnifyPortが担う範囲

UnifyPortは、Meta configurationsの移行、Cloud API permissionsの付与、公式Business App履歴の同期、MetaのCoexistence状態の維持を行いません。製品にこれらの公式機能が必要なら、v4が正しい経路であり、integration ownerには移行が必須です。

UnifyPortが対応するのは別の要件です。通常のWhatsApp accountを接続し、対応するinbound messagesを標準のmessage.received webhook eventとして受信します。WhatsApp authorizationではQR codeとphone-number pairingを利用でき、signed webhook deliveryではX-Device-Timestamp、X-Device-Signature、endpointのsigning_secretを使います。

本当に必要なのがBusiness AppとCloud APIで同じ電話番号を共有することではなく、inbound queueである場合、この代替案を検討できます。不要な公式機能の移行へ開発工数を投じる前に、WhatsApp inbound pathsガイドで3つの方法を比較してください。

制限とトレードオフ

顧客を公式Cloud API productsへonboardするSolution PartnersとTech Providersには、Embedded Signup v4が正しい選択です。この比較の中で、MetaがサポートするCoexistenceの動作、履歴共有フロー、公式asset model、Cloud API product permissionsを維持できる唯一の経路でもあります。

非公式インターフェースは、これらの権限を提供できません。企業をMeta productsの対象にすることも、Metaのcustomer-service windowsを置き換えることも、通常のaccount connectionをCloud API WABAへ変えることもできません。提供できる範囲は限定的で、顧客に公式Coexistence stackの利用を求めずに、標準のinbound interfaceを提供します。

V4への移行によって、Coexistence向けに記載された運用制限がなくなるわけでもありません。Metaは現在、Business AppとCloud APIの両方で使う電話番号について、毎秒20メッセージに固定されたスループット、API送信メッセージへのCloud API料金、非対応のgroup-history synchronization、companion-device固有の制限を案内しています。受け入れテストでは、これらの条件を公式ガイドでもう一度確認してください。

FAQ

Metaによると、Embedded Signup v2は2026年10月15日に廃止されます。Integration ownerはonboardingの中断を避けるため、それまでにv4へ移行してください。

すべてのWhatsApp Business Appユーザーに移行が必要？

いいえ。移行するのは、Embedded Signup v2 integrationを所有するpartnerまたはproviderです。単体のWhatsApp Business Appだけを利用する企業は、Embedded Signup configurationを管理していません。

V4ではWhatsApp Coexistenceがなくなる？

なくなりません。Metaは、WhatsApp Business Appユーザーのonboardingをv4でも引き続きサポートすると案内しています。デフォルトのCloud APIフローと同じだと考えず、専用のCoexistence選択肢を維持してテストする必要があります。

必要です。Metaのv4ガイドでは、新しいconfigurationを作成し、login variationとしてEmbedded Signupを選び、含めるproductsを選択するよう案内しています。

移行テストでは何を確認すべき？

最低限、既存Business Appへの接続オプションが表示されること、finish callbackとassetsが返ること、token exchangeが完了すること、is_on_biz_appがtrueかつplatform_typeがCLOUD_APIになること、history、smb_app_state_sync、smb_message_echoesのwebhook経路が動作することを確認します。

次のステップ

Meta Embedded Signup integrationを管理している場合は、公式v4移行ガイドに沿って新しいconfigurationを作成し、stagingで上のチェックリストを実行してください。通常accountのinbound messagingだけが必要なら、Coexistenceを構築する前にUnifyPort WhatsApp authorizationガイドで別の経路を評価できます。

Sources

以下のMeta公式情報を2026-07-16に確認しました。