クラウドAPIからオンプレミスAPIへのマイグレーション

オンプレミスAPIを終了します。詳細と次世代クラウドAPIへの移行方法については、オンプレミスAPIの終了のドキュメントを参照してください。

このドキュメントは、クラウドAPIからオンプレミスAPIにビジネス電話番号をマイグレーションする方法を説明しています。オンプレミスAPIからクラウドAPIへのマイグレーションについては、オンプレミスAPIからクラウドAPIへのマイグレーションを参照してください。

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

マイグレーションしても次のものには影響しません。

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

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

ベストプラクティス

アプリがすべてのAPIの違いに対応できることを確認した後、まず少しの数のビジネス電話番号を移行し、オンプレミスAPIで提供するつもりのすべての機能が正しく動作することを確認してください。すべて正しく機能することを確認してから、追加の番号を移行するようにしてください。

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

API間の違い

マイグレーションプロセスを始める前に、API間の違いにアプリが対応できることを確認しておいてください。

Webhooks

クラウドAPIとビジネス管理APIのWebhooksのペイロード構造は、オンプレミスAPIのペイロード構造とは異なります。オンプレミスAPI Webhooksを独占的に処理する新しいWebhooksエンドポイントを作成することをおすすめします。

ペイロードの違いを理解するのに役立つ、次のドキュメントを参照してください:

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

オンプレミスAPIへのマイグレーションが完了すると、ビジネス電話番号のクラウドAPI Webhooksは配信されなくなり、オンプレミスAPI Webhooksの配信が始まります。

メディア

クラウドAPIにアップロードされたメディアのメディアIDは、オンプレミスAPIでメッセージを送信するときには使用できません。そのため、オンプレミスAPIを使ってメディアを再アップロードして新しいメディア IDを生成するか、メディアが公開サーバーでホストされているなら、メディアURLを使用しなければなりません。メディアメッセージの送信をご覧ください。

エラーコード

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

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

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

ダウンタイム

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

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

ステップ1: オンプレミスAPIを統合する

ビジネス電話番号をオンプレミスAPIに移行するため、アプリがオンプレミスAPIクライアントを正常に使用できること、ビジネス電話番号に関連付けられているWhatsAppビジネスアカウントでWebhooksが正しく設定されていることを確認してください。

ステップ2: 移行の準備をする

移行中はメッセージの送信を停止することをおすすめします。

WhatsApp Business APIオンプレミスクライアントでWhatsAppサーバーに接続するには、特定のネットワーク要件があります。準備ができていることを確認するには、ネットワークの設定とデバッグをチェックしてください。

ステップ3: APIクライアントを登録する

オンプレミスAPIクライアントにビジネス電話番号を登録します。そのために、/accountエンドポイントを呼び出します。

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

受信した応答に応じて、登録手続きが完了したと見なしてよい場合と、完了するにはさらに手順を踏むことが必要な場合があります。成功した場合は、次のいずれかのHTTPステータスコードが返されます。受信した応答に応じた手順に従ってください。

201 Created — アカウントがすでに存在します。すでに登録されているため、他に必要な作業はありません。
202 Accepted — アカウントが存在しません。リクエストで選択した方法に応じて、SMSまたは音声番号を確認して登録コード取得します。この応答には返されたペイロードが含まれており、その中にcertパラメーターからデコードされたvnameがあります。これで、正しい表示名が設定されていることを確認できます。正しければ、アカウント登録の完了に進んで登録を完了します。

このエンドポイントの利用可能なすべてのフィールドについては、こちらをご覧ください。

登録が完了すると、オンプレミスAPIクライアントがメッセージを受信するようになります。

ステップ4: シャードを設定する

クライアントが登録されたら、必要に応じてシャードを設定することができます。

ステップ5: メッセージの送信を開始する

顧客にメッセージを送る準備ができました。ガイダンスについては、メッセージの送信ガイドをご覧ください。

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