オンプレミスAPIからクラウドAPIに移行する

このドキュメントでは、ビジネス電話番号をオンプレミスAPIからクラウドAPIに移行する方法について説明します。

API間でのビジネス電話番号の移行は、WhatsAppビジネスアカウント(WABA)間での電話番号の移行とは異なることに注意してください。

クラウドAPIからオンプレミスAPIに移行する方法については、クラウドAPIからオンプレミスAPIへの移行をご覧ください。

処理の概要

移行処理には、ビジネス電話番号についてのメタデータを生成してから、クラウドAPIでの使用のためにそのデータを使って番号を登録することが関係します。それにより、その番号はオンプレミスAPIから登録解除されます。1つの番号は、1つのAPIにしか登録できないからです。

移行しても次のものには影響しません。

そのビジネス電話番号の表示名、認証ステータス、品質評価
そのビジネス電話番号で使われているテンプレート、またはそのステータス
所有者WABA、その公式ビジネスアカウントのステータス、そのメッセージ制限

しかし、移行をサポートするには、このドキュメントに記載されている移行手順を実行する前に、API間の違いに注意し、それに対処するための適切な措置を取る必要があります。

要件

Metaアプリ

顧客データがオンボーディングされている状態でクラウドAPIとビジネス管理APIを使うことができ、さらにクラウドAPIとビジネス管理APIのWebhookに対応できるMetaビジネスアプリが必要です。さらにアプリは、認証済みのMetaビジネスアカウントに関連付けられているか、またはそれによって要求されているものでなければなりません。

Metaビジネスアプリがない場合、またはアプリはあるもののWhatsApp製品をアプリに設定していない場合は、クラウドAPIのスタートガイドにある手順を完了してください。これらのステップを完了すると、クラウドAPIとビジネス管理APIをテストするために必要なアセットがすべて生成されます。

アプリレビュー

該当Metaアプリについて、アプリレビューを実施し、whatsapp_business_messagingアクセス許可とwhatsapp_business_managementアクセス許可の承認を得る(アドバンスアクセスを得る)必要があります。

ベストプラクティス

アプリがAPI間の相違点をすべて処理できることを確認したら、まず低ボリュームのビジネス電話番号のいずれかを移行して、クラウドAPIで提供予定の機能がすべて適切に動作することを検証するようおすすめします。すべて正しく機能することを確認してから、追加の番号を移行するようにしてください。

また、移行作業は、オンプレミスAPIデプロイへのトラフィックが少ない時間帯に実行するようにおすすめします。

API間の違い

オンプレミスAPIの以下の機能は、クラウドAPIでサポートされていないか、または処理方法が異なります。移行処理を始める前に、それらの違いをアプリで処理できることを確認しておいてください。

Webhooks

クラウドAPIとビジネス管理APIのWebhookのペイロード構造体は、オンプレミスAPIのペイロード構造体とは異なります。クラウドAPIとビジネス管理APIをそれぞれ専用に処理できる新しいWebhookエンドポイントを作成することをおすすめします。

ペイロードの違いについて、またアプリダッシュボードを使ってアプリに対するWebhookを設定する方法について詳しくは、以下のドキュメントをご覧ください。

設定: WhatsApp用Webhook
クラウドAPIのWebhooksペイロード: Webhooks通知ペイロードのリファレンス
ビジネス管理API Webhookペイロード: Webhookの設定

ビジネス電話番号をクラウドAPIに移行したら、[WhatsAppビジネスアカウント] > [サブスクリプション登録対象アプリ]エンドポイントを使って、Metaアプリを、そのビジネス番号に関連するWABAのWebhookに登録する必要があることに注意してください。

リクエストの構文

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

クラウドAPIへの移行が完了すると、ビジネス電話番号のオンプレミスAPI Webhooksの配信が終了し、クラウドAPI Webhooks配信が開始されます。

メディア

クラウドAPIでメッセージを送信する際に、オンプレミスAPIにアップロードされるメディアのメディアIDを使うことはできません。したがって、クラウドAPIを使ってメディアをアップロードし直すことによって新しいメディアIDを生成するか、またはメディアが公開サーバー上でホスティングされている場合はメディアURLを使う必要があります。メディアメッセージとメディアベースのメッセージテンプレートをご覧ください。

メッセージの整合性を確保するため、オンプレミスAPIで許可されているメディアホスティングドメインの一部が、クラウドAPIでは許可されないことに注意してください。メディア用にホスティングサービスを使う場合は、移行の前にフリーフォームメッセージやテンプレートメッセージでメディアURLをテストすることをおすすめします。エラーのためにホストがブロックされていると思われる場合は、サポート担当にご連絡ください。

エラーコード

クラウドAPIとビジネス管理APIのエラーコードは、オンプレミスAPIのエラーコードとは異なります。以下のドキュメントをご覧ください。

プロパティの検証

オンプレミスAPIではメッセージ投稿本文のペイロードの中に含まれる不明プロパティを受け付け可能ですが、クラウドAPIではそのようなリクエストが却下されるため、メッセージ送信リクエストではサポートされるプロパティだけを使うようにしてください。
オンプレミスAPIでは、ボタンが1個だけのメッセージを送信する際にボタンインデックスを省略できますが、クラウドAPIではそのようなリクエストが却下されるため、ボタンが含まれるメッセージ送信リクエストにインデックスとその値が含まれていることを確認してください。
オンプレミスAPIでは、インタラクティブメッセージ送信時にアクションとボタンのオブジェクトプロパティの先頭や末尾にスペースが含まれる(またはスペースのみの)テキスト文字列が受け付けられます。しかし、クラウドAPIでは、そのようなリクエストは却下されます。

プッシュツートークメッセージ

オンプレミスでは、messages.typeをvoiceに設定することによりWebhookの中のプッシュツートーク(PTT)メッセージが識別されます。しかし、クラウドAPIの場合、PTTメッセージは、messages.audio.voiceをtrueに設定することによって識別されます。

スタンプパック

クラウドAPIでは、スタンプパックがサポートされていません。

ダウンタイム

移行の最終ステップを実行すると、すぐに(クラウドAPI用に番号を登録するため)ダウンタイムが始まります。それはほんの数秒間のはずです。その間、WhatsAppユーザーからその番号に送信されるメッセージは、痕跡を残さずに削除されることになります。

ダウンタイムによる影響を最小限に抑えるため、該当番号のアクティビティ量が低いタイミングに移行作業を実施するようスケジュールすることをおすすめします。

スループット

オンプレミスビジネス電話番号に複数のシャードが実行されているマルチコネクトがある場合、その番号はクラウドAPIでは自動的に高スループットにアップグレードされます。

公式ビジネスアカウント

公式ビジネスアカウント(OBA)のステータスがあるビジネスの電話番号を移行する場合、番号の登録時(ステップ3)にそのメタデータ(ステップ2で生成)を含めると、そのステータスは保持されます。このデータを省略すると、その電話番号はOBAステータスを失います。

移行のサポート

移行に関して質問がある場合や、サポートが必要な場合は、以下のようにダイレクトサポートチケットを送信してください。

トピック: WABiz: Cloud API
リクエストタイプ: On-Premises API -> Cloud API Migration Issues

ステップ1: 2段階認証を無効にする

ビジネス電話番号のPINが分かっている場合は、このステップをスキップできます。

ステップ3を実行する際にビジネス電話番号のPINが必要になるため、PINが分からない場合は、まずそのビジネス電話番号に対する2段階認証を無効にする必要があります。そのビジネス電話番号の所有者でない場合は、それを無効にするよう所有者に依頼してください。

ステップ2: 電話番号メタデータを生成する

ビジネス電話番号についてのメタデータを生成するには、バックアップと復元APIを使います。

リクエストの構文

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD>は、任意の文字列にすることができます。この値は、メタデータをエンコードするために使われます。次のステップで必要になるため、値を把握しておいてください。

応答

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

該当するビジネス電話番号とその設定について記述するdataプロパティに割り当てられているエンコード済み文字列がAPIから返されます。この値は次のステップで必要になるため、メモしておいてください。

<METADATA> — これは、該当のビジネス電話番号とその設定について記述するエンコード済み文字列です。この値は次のステップで必要になるため、メモしておいてください。
<API_STATUS> — オンプレミスAPIデプロイのステータス。
<API_VERSION> —実行するオンプレミスAPIのバージョン番号。

リクエストの例

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

応答の例

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

ステップ3: 番号を登録する

クラウドAPIの[WhatsAppビジネス電話番号] > [登録]エンドポイントを使って、クラウドAPIで使用するために番号を登録します。

前のステップで得られたエンコード済みビジネス電話番号メタデータ値とパスワードを含めます。このデータがなくても番号を登録できますが、含めない場合、ビジネス電話番号のプロフィールデータが失われてしまいます。これは、公式ビジネスアカウントとしてのWhatsAppビジネスアカウントのステータスに影響を与えることがあります。

リクエストの構文

POST /<BUSINESS_PHONE_NUMBER_ID>/register

投稿本文

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> — ビジネス電話番号の既存PINまたは今回設定するPIN。
<PASSWORD> — 前のステップでビジネス電話番号のメタデータを生成するために使ったパスワード。
<METADATA> — 前のステップで生成された、ビジネス電話番号とその設定について記述するエンコード済み文字列。

応答

{
  "success": <SUCCESS>
}

APIからの応答では、登録が成功した場合はsuccessがtrueに、エラーが発生した場合はfalseに設定されます。

リクエストの例

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

応答の例

{
  "success": true
}

ステップ4: メッセージ機能の正常性ステータスをチェックする(任意)

ビジネス電話番号のhealth_statusフィールドをリクエストし、それをクラウドAPIのメッセージングに使うことができることを確認します。メッセージ機能の正常性ステータスをご覧ください。

WhatsApp Businessプラットフォーム | クラウドAPI | Business管理API