クラウドAPI

クラウドAPIのローカルストレージ

クラウドAPIのローカルストレージには、メッセージデータが保存される場所を管理するオプションがあります。金融、政府、医療などの規制された業界に属する会社では、規制や会社のポリシーに準ずるためメッセージデータを特定の国に保存しておきたい場合があります。

クラウドAPIは、追加のデータ管理コントロールを実装することで、そのような追加のデータ保護レイヤーを提供します。ローカルストレージ機能は、クラウドAPIランタイム環境における次の2つの追加の制約によって構成されています。

  • 使用中のデータのTTL(生存期間): クラウドAPIが、メッセージコンテンツの処理の間に、対象となる管轄外でどれだけの時間そのコンテンツにアクセスできるかを決定する、新たなデータ保持制約が実装されます。ローカルストレージを使用する場合、クラウドAPIは、60分のTTLが過ぎると「使用中のデータ」ストレージ(キャッシュ、キューなど)からメッセージコンテンツを自動的に削除します。TTLの後、機密メッセージコンテンツは米国のクラウドAPIサーバーに存在しなくなります。
  • 保存データのロケーション: 機密メッセージコンテンツ用の永続ストレージとしてクラウドAPIが使用できる物理ロケーションを決定する、データ配置に関する新しい制約が実装されます。受信メッセージと送信メッセージ両方のテキストとメディアペイロードは、国内(米国外)のクラウドAPIに保存されます。

ビジネス電話番号に対してローカルストレージが有効化されると、クラウドAPIは、米国を拠点とするデフォルトのストレージの代わりに、指定された国のローカライズ済みストレージを使用して永続メッセージコンテンツを保存します。

ローカルストレージ機能は他のクラウドAPIのプライバシーとセキュリティコントロールを補完し、顧客がローカルデータ保護規制をより高いレベルで確実に遵守できるようにします。

ローカライズ済みデータ

クラウドAPIには、メッセージコンテンツのローカライズ機能が実装されています。ローカルストレージ機能は、次のメッセージフローに対応しています。

  • 送信メッセージ: クラウドAPIで受信者に送信しているメッセージ
  • 受信メッセージ: クラウドAPIを介して受信しているメッセージ

ローカルストレージ機能は、次のメッセージタイプに対応しています。

  • テキストメッセージ: テキストペイロード(メッセージ本文)がローカライズされる
  • メディアメッセージ: メディア(音声、ドキュメント画像、または動画)ペイロードがローカライズされる
  • テンプレートメッセージ: テキストペイロードまたはメディアペイロードを持つコンポーネントがローカライズされる

また、暗号化されたローカライズ済みのメッセージペイロードと、元々の処理されたメッセージを正しく関連付け、ローカライズの事実を監査するために、ローカライズ済みのデータセットにメタデータアトリビューションの限定されたセットが組み込まれています。メタデータはトークン化と暗号化によって保護されています。

クラウドAPIローカルストレージ機能の目標は、ビジネスがクラウドAPIを設定することで機密データの保存場所を直接コントロールできるようにすると同時に、データの配置場所をグローバルに選べる柔軟性が得られるようにすることです。

利用可能な地域

現在、クラウドAPIローカルストレージがサポートされている地域は以下のとおりです。地域は、ローカルストレージ機能を有効にする際に選択できます。

  • APAC: インド、シンガポール、インドネシア、韓国、日本、オーストラリア
  • LATAM: ブラジル
  • MEA: 南アフリカ、バーレーン、アラブ首長国連邦
  • ヨーロッパ: EU(ドイツ)、英国、スイス
  • NORAM: カナダ

要件

ローカルストレージは、ビジネス電話番号が未登録状態にある場合にのみ、その番号に対して有効または無効にできます。

ローカルストレージを有効にする

APIバージョン21.0以降を使用して、未登録のビジネス電話番号に対してローカルストレージを有効にするには、以下の手順に従ってください。古いAPIバージョンを使用している場合は、ローカルストレージを有効にする(v20以前)を参照してください。

ステップ1: 該当の番号でローカルストレージを有効にする

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settingsエンドポイントを使って、未登録のビジネス電話番号でローカルストレージを有効にします。

リクエストの構文

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED", 
    "data_localization_region": "<COUNTRY_CODE>"
  }
}

<COUNTRY_CODE>を、保存中データが保存されるべき国の国コードに設定します。

応答の構文

{
  "success": <SUCCESS>
}

正常に完了すると、<SUCCESS>がtrueに設定されます。

リクエストの例

curl 'https://graph.facebook.com/v21.0/106540352242922/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED", 
    "data_localization_region": "BR"
  }
}'

応答の例

{
  "success": true
}

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

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/registerエンドポイントを使って、ビジネス電話番号を登録します。

リクエストの構文

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/register

{
  "messaging_product": "whatsapp",
  "pin": "<TWO_STEP_PIN>"
}

<TWO_STEP_PIN>を、ビジネス電話番号に対応する任意の2段階認証PINに設定します。

応答の構文

{
  "success": <SUCCESS>
}

正常に完了すると、<SUCCESS>がtrueに設定されます。

リクエストの例

curl 'https://graph.facebook.com/v21.0/v21.0/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456"
}'

応答の例

{
  "success": true
}

ローカルストレージの設定を取得する

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settingsエンドポイントを使って、WhatsApp Businessの電話番号のローカルストレージ設定を取得します。以下はその例です。

curl 'https://graph.facebook.com/v21.0/179776755229976/settings' \
-H 'Authorization: Bearer EAAJB...'

これにより、該当するビジネス電話番号のローカルストレージ設定を表すノードが返されます。以下はその例です。

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_ENABLED",
    "data_localization_region": "BR"
  }
}

ローカルストレージを無効にする

APIバージョン21.0以降を使って、未登録のビジネス電話番号のローカルストレージを無効にするには、POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settingsエンドポイントを使用します。古いAPIバージョンを使用している場合は、ローカルストレージを無効にする(v20以前)を参照してください。

リクエストの構文

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/>settings

{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_DISABLED"
  }
}

<COUNTRY_CODE>を、保存中データが保存されるべき国の国コードに設定します。

応答の構文

{
  "success": <SUCCESS>
}

正常に完了すると、<SUCCESS>がtrueに設定されます。

リクエストの例

curl 'https://graph.facebook.com/v21.0/106540352242922/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "storage_configuration": {
    "status": "IN_COUNTRY_STORAGE_DISABLED"
  }
}'

応答の例

{
  "success": true
}

ローカルストレージを有効にする(v20以前)

APIバージョン20.0以前を使用して、未登録のビジネス電話番号に対してローカルストレージを有効にするには、以下の手順に従ってください。

ステップ1: 認証ステータスをチェックする

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER>エンドポイントを使って、code_verification_statusフィールドをリクエストします。コード認証ステータスがVERIFIEDの場合は、ステップ4に進みます。それ以外の場合は、ステップ2に進みます。

ステップ2: 認証コードをリクエストする

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/request_codeエンドポイントを使って、認証コードをリクエストします。正常に完了すると、APIはtrueを返し、code_methodパラメーターで指定された方法で認証コードがビジネス電話番号に送られます。

例えば、このクエリは、認証コードをSMS経由で英語(USロケール)で送信することを要求します。

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

受信したメッセージ内のコードは次のステップで使用します。

ステップ3: ビジネス電話番号を認証する

ステップ2で受信したメッセージに含まれる認証コードを使ってビジネス電話番号を認証するには、POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/verify_codeエンドポイントを使用します。

以下はその例です。

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/verify_code?code=123830' \
-H 'Authorization: Bearer EAAJB...'

ステップ4: ビジネス電話番号を登録する

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/registerエンドポイントを使って、ビジネス電話番号を登録します。data_localization_regionパラメーターを使って、保存中データが保存される国を指定します。

例えば以下のリクエストは、ビジネス電話番号のローカルストレージを有効にし、データを保存する国をインドに設定します。

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "123456",
  "data_localization_region": "IN"
}'

ローカルストレージを無効にする(v20以前)

APIバージョン20.0以前を使って、未登録のビジネス電話番号のローカルストレージを無効にするには、POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/deregisterエンドポイントを使用します。

以下はその例です。

curl -X POST 'https://graph.facebook.com/v21.0/110200345501442/deregister' \
-H 'Authorization: Bearer EAAJB...'

これはビジネス電話番号の登録を削除することになるため、WhatsApp Cloud APIでは使用できません。ローカルストレージを有効にすることなくCloud APIで使用を続けたい場合は、data_localization_regionパラメーターを含めずに再登録する必要があります。

よくある質問

Q.ローカルストレージを使用するクラウドAPIバージョンに電話番号を移行する手順はどのようなものですか?

Metaでは、ローカルストレージを使用するクラウドAPIバージョンへの移行手順をすべてサポートしています。例えば、以下のような手順があります。

  • 既存のオンプレミスAPI番号を、ローカルストレージを使用するクラウドAPIバージョンに移行する
  • 既存のクラウドAPI番号を、ローカルストレージを使用するクラウドAPIバージョンに移行する
  • 新しいクラウドAPI番号でローカルストレージを有効にする

いずれのシナリオでも、新しいパラメーターdata_localization_regionでデータがローカライズされる対象の国を指定して、選択された電話番号の/registerエンドポイントにPOSTリクエストを送信する必要があります。

Q.移行のリスクはありますか?この移行作業に関連してダウンタイムが発生しますか?

移行にリスクはありません。このプロセスは、オンプレミスAPIからクラウドAPIへの移行と同様です。こちらの開発者ドキュメントをご覧ください。ダウンタイムは通常5分以内であり、ビジネス電話番号の再認証は不要です。