WhatsApp Businessプラットフォーム

認証済み電話番号

このドキュメントでは、新しい埋め込み登録フローの中で、エンドクライアントに認証済みビジネス電話番号を提供する方法について説明します。認証済みビジネス電話番号は、開発者によってすでに認証されたビジネス電話番号です。この電話番号があれば、エンドクライアントが開発者にワンタイムパスワードを問い合わせる必要がなくなります。

Screenshot of pre-verifed phone numbers in Embedded Signup flow

認証済みビジネス電話番号は、一時的なWhatsApp Business認証済み電話番号オブジェクトによって表されることに注意してください。エンドクライアントがこれらの番号の1つを選択して新しい埋め込み登録フローを完了すると、一時オブジェクトは、WhatsApp Business電話番号オブジェクトによって置き換えられるため、この電話番号を登録するために新しいオブジェクトのIDを入手する必要があります。

要件

制限

  • 新しい埋め込み登録フローでのみ利用可能です。新しいフローを有効にする方法について詳しくは、登録フローを埋め込むのドキュメントをご覧ください。
  • 認証済みビジネス電話番号を請求した人を記録する責任は、開発者側が負います。
  • エンドクライアントが認証済みビジネス電話番号を認証から90日以内に埋め込み登録フローで請求しないと、その番号は未認証ステータスに戻り、次の90日以内にステータスを復元するための再認証が必要になります。
  • 未請求の認証済みビジネス電話番号は、未認証ステータスに戻す予定日の45日前になるまでは再認証できません。この予定日は、verification_expiry_timeフィールドに示されます。
  • 電話番号を認証済み電話番号プールに追加(ステップ1)したのに、90日以内に認証(ステップ3)しなかった場合、その番号はプールから削除されるため、再度追加する必要が生じます。

認証済み電話番号の作成

これらの手順に従って認証済みビジネス電話番号を作成し、埋め込み登録を行って表示し、エンドクライアントによる請求後に登録してください。

ステップ1: 認証済みビジネス電話番号を作成する

[ビジネスアカウント] > [電話番号を追加]エンドポイントを使って、ビジネスの認証済みビジネス電話番号を作成します。作成した番号は、自分の電話番号プールに追加されます。

リクエストの構文

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

応答

成功した場合、APIからWhatsApp Business認証済み電話番号のIDが返されます。次回リクエストでの使用に備えて、その値をメモしておいてください。

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

リクエストの例

curl -X POST 'https://graph.facebook.com/v20.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

応答の例

{
  "id": "106540352242922"
}

サポートされている電話番号の形式とクエリパラメーターについては、[ビジネスアカウント] > [電話番号を追加]エンドポイントのリファレンスをご覧ください。

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

[WhatsApp Business認証済み電話番号] > [コードをリクエスト]エンドポイントを使って、SMSまたは音声により、新たに作成された認証済みビジネス電話番号用のワンタイムパスワードをリクエストします。

リクエストの構文

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

応答

成功すると、APIからtrueが返されます。

{
  "success": <SUCCESS>
}

さらに、その電話番号に対するワンタイムパスワードを含むSMSまたは音声メッセージが届きます。次回リクエストでの使用に備えて、このワンタイムパスワードをメモしておいてください。

ワンタイムパスワードSMSの構文

WhatsApp code <CODE>

ワンタイムパスワード音声メッセージの構文

3回繰り返されます。

Verification code is <CODE>

リクエストの例

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

応答の例

{
  "success": true
}

ワンタイムパスワードSMSメッセージの例

WhatsApp code 123-456

ワンタイムパスワード音声メッセージの例

3回繰り返されます。

Verification code is 123456

サポートされるコード方式、言語、クエリのパラメーターについては、[WhatsApp Business認証済み電話番号] > [コードをリクエスト]エンドポイントのリファレンスをご覧ください。

ステップ3: 番号を認証する

[WhatsApp Business認証済み電話番号] > [コードを認証]エンドポイントを使い、ワンタイムパスワードを使ってビジネス電話番号を認証します。

リクエストの構文

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

応答

成功すると、APIからtrueが返されます。さらにそのビジネス電話番号のcode_verification_statusが、90日間VERIFIEDに設定されます。

{
  "success": <SUCCESS>
}

リクエストの例

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

応答の例

{
  "success": true
}

サポートされるクエリパラメーターについては、[WhatsApp Business認証済み電話番号] > [コードを認証]エンドポイントのリファレンスをご覧ください。

ステータスが認証済みになっている認証済み電話番号(またはそのような番号のセット)の用意ができたら、新しい埋め込み登録フローでそれらを表示します。

埋め込み登録で認証済み電話番号を表示する

認証済みビジネス電話番号は、入力済みフォームデータにより、新しい埋め込み登録フローで表示できます。そのためには、idsプロパティが設定されたpreVerifiedPhoneオブジェクトをsetupオブジェクトに追加し、認証済みビジネス電話番号のIDを、idsプロパティへの文字列配列として割り当てます。

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

例:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

VERIFIEDステータスの認証済みビジネス電話番号が、認証から90日間以内に請求されない場合、その番号のステータスはUNVERIFIEDになりますが、新しい埋め込み登録フローには表示されたままになります。未認証の番号の請求を試みるエンドクライアントは、自分で認証処理を完了する必要があります。これはつまり、エンドクライアントからのワンタイムパスワードのリクエストが必要になるということです。

このようなユーザーエクスペリエンスは不便であり、そうならないようにするため、番号をいつ認証したかを常に記録しておき、未認証状態に戻る前に再認証することをおすすめします。

特定の認証済みビジネス電話番号を最後に認証した時点が不明な場合は、WhatsApp認証済みビジネス電話番号エンドポイントをクエリし、最新の認証時間を示すcode_verification_timeフィールドと認証期限を示すverification_expiry_timeフィールドを確認してください。

番号が埋め込み登録によって請求されたかどうかを判断する

請求された電話番号IDの取得をご覧ください。

請求された電話番号IDを取得する

[WhatsApp Businessアカウント] > [電話番号]エンドポイントに対してGETを実行します。これにより、WhatsApp Businessアカウント上のすべてのWhatsApp Business電話番号が返されます。

結果セットで返される各オブジェクトのdisplay_phone_numberプロパティを解析します。オブジェクトにdisplay_phone_number値として表示電話番号が設定されている場合(例: 16505551234)、その番号はすでに請求済みです。そのオブジェクトのidプロパティの値をコピーします。これは、新しいWhatsApp Business電話番号番号オブジェクトのIDであり、この時点でこの番号を表すものになります(旧IDは機能しなくなります)。

あるいは、field拡張機能により同じエンドポイントを使うことで、display_phone_numberフィールドをリクエストして、表示電話番号を指定することもできます。例:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

これでWhatsApp Business電話番号オブジェクトとともに表示電話番号が返される場合、その番号は請求済みです。そのオブジェクトのidをコピーしておいてください。

認証済みビジネス電話番号を取得する

[ビジネスアカウント] > [認証済み番号]エンドポイントを使って、すべてのWhatsApp Business認証済み電話番号オブジェクトのリストを取得します。その際には、ビジネスアカウントの認証済みビジネス電話番号プールに入っているそれらの番号の認証ステータスは問われません。

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

結果は、自動的に作成時刻順にソートされます。また、フィールド拡張機能を使ってcode_verification_statusフィールドをリクエストすることにより、指定した認証ステータスの認証済みビジネス電話番号だけがAPIから返されるようにすることもできます。

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

事前認証済み電話番号を共有/共有解除する

[ビジネス] > [認証済み電話番号の共有]エンドポイントにPOSTリクエストを送信して認証済みビジネス電話番号をビジネスパートナーと共有するか、同じエンドポイントにDELETEリクエストを送信して共有を解除します。

共有された認証済みビジネス電話番号は、ビジネスパートナーによる埋め込み登録フローによって表示することができます。

複数のビジネスパートナーと電話番号を共有している場合は、埋め込み登録を行ってそれらの番号を表示する前に、共有した認証済み電話番号のリストを取得するようパートナーにアドバイスすることをおすすめします。これにより、パートナーが請求済みの電話番号を表示させようと試みる(請求済みの電話番号はフローには表示されませんが、パートナーがこのことを把握しておらず、なぜ表示されないのか疑問に思うかもしれません)可能性を減らせます。

リクエスト構文を共有する

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

リクエスト構文の共有を解除する

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

応答

成功すると、APIからtrueが返されます。共有する場合は、ビジネスパートナーに新たに共有された認証済み番号を通知し、番号のIDを提供してください。共有を解除する場合は、パートナーの埋め込み登録の実装に番号が表示されなくなります。

{
  "success": <SUCCESS>
}

共有リクエストの例

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

リクエストの共有解除の例

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

応答の例

{
  "success": true
}

認証済み電話番号をプログラムを使って登録する

埋め込み登録の電話番号選択手順を完全に省略して、オンボーディングされたエンドクライアントのWhatsApp Businessアカウントに認証済みビジネス電話番号をプログラムを使って登録することができます。その手順は電話番号を登録ドキュメントのステップに従いますが、ステップ1で認証済みビジネス電話番号のIDを使い、ステップ4までスキップしてください。

リクエストの構文

このリクエストを利用して、認証済みビジネス電話番号のIDを使ってWhatsApp BusinessアカウントのWhatsApp Business電話番号を作成します。この手順は、ステップ1に置き換わります。

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

POST本文

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

プロパティ

プレースホルダー説明値の例

<PREVERIFIED_ID>

文字列

必須。


認証済みビジネス電話番号のID。

6635066806614622

<COUNTRY_DIAL_CODE>

文字列

必須。


認証済みビジネス電話番号の国際電話の国番号。

1

<DISPLAY_PHONE_NUMBER>

文字列

必須。


認証済みビジネス電話番号の表示電話番号。

5550783881

<VERIFIED_NAME>

文字列

必須。


認証済みビジネス電話番号の表示名。

Lucky Shrub

応答の構文

成功すると、APIからWhatsApp Business電話番号のIDが返されます。このIDを使って電話番号を登録します(電話番号を登録するドキュメントのステップ4)。

{
  "id": "<ID>"
}

応答のプロパティ

プレースホルダー説明値の例

<ID>

WhatsApp Business電話番号のID。


このオブジェクトはWhatsApp Businessの認証済み電話番号オブジェクトに置き換えられました。

108692048990658

リクエストの例

curl 'https://graph.facebook.com/v20.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

応答の例

{
  "id": "108692048990658"
}