電話番号

このガイドでは、電話番号の認証方法と、クラウドAPIに対応するフォーマットについて説明します。

WhatsApp Businessアカウント(WABA)に追加できる電話番号の種類には条件があります。詳しくは、電話番号をご覧ください。

掲載されているAPI呼び出しの中には、電話番号IDを把握しておく必要があるものもあります。WABAに関連付けられている電話番号を取得する方法については、すべての電話番号を取得するをご覧ください。API呼び出し応答には、WhatsApp Businessアカウントにリンクしている各電話番号のIDが含まれます。/PHONE_NUMBER_ID呼び出しで使用する電話のIDを保存してください。

電話番号を認証する

顧客へのメッセージの送信に使用する電話番号は、認証が必要です。電話番号は、SMS/音声通話で通知されるコードを使って認証します。認証処理は、次の手順で、グラフAPI呼び出しによって実行できます。

グラフAPIを使って電話番号を認証するには、PHONE_NUMBER_ID/request_codeに対してPOSTリクエストを実行します。呼び出しには、選択した認証方式と言語を含めます。

パラメーター

例

リクエストの例:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

API呼び出し後に、選択した方式で認証コードを受け取ります。認証処理を終了するには、PHONE_NUMBER_ID/verify_codeに対するPOSTリクエストに、自分の認証コードを含めます。

パラメーター

例

リクエストの例:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

成功した場合の応答は次のようになります。

{
  "success": true
}

本人確認情報の変更チェック

顧客にメッセージを配信するにあたり、顧客の本人確認を行いたいと思うかもしれません。ビジネス電話番号で本人確認情報の変更チェック設定を有効にすることで、これを行うことができます。

顧客がWhatsAppで個人情報を変更したと思われるアクションを実行した場合、ユーザーの新しいIDハッシュが生成されます。ビジネス電話番号で本人確認情報の変更チェック設定を有効にすると、顧客にメッセージを配信する際にいつでもこのハッシュを取得できます。また、これを有効にすることで、顧客からメッセージを送信するときや、IDハッシュなしで顧客へメッセージを送信するときは常に、受信メッセージWebhooksまたは配信ステータスWebhooksに当該ハッシュが含まれるようになります。このハッシュは、今後の使用のためにキャプチャして保管することが可能です。

ハッシュを使用するには、送信メッセージリクエストにハッシュを含めてください。Metaがリクエストに含まれるハッシュと顧客の現在のハッシュを比較します。ハッシュが一致すると、メッセージが配信されます。一致しない場合、最後にメッセージを配信してから顧客の本人確認情報が変更されていることを意味するため、メッセージは配信されません。代わりにMetaより、エラーコード(137000)を含むメッセージステータスWebhookをお送りし、配信できなかった旨とハッシュの不一致をお知らせします。

ハッシュの不一致Webhookを受け取ったら、顧客の電話番号の信頼性はなくなったものと考えられます。信頼を再度確立するには、WhatsApp以外のチャネルを使用して顧客の本人確認をもう一度行ってください。信頼を再度確立したら、配信に失敗したメッセージを新しい本人確認情報(該当する場合)にハッシュなしで再送します。その後、メッセージステータス配信Webhookに含まれる顧客の新しいハッシュを保管してください。

リクエストの構文

[WhatsApp Business電話番号] > [設定]エンドポイントにPOSTリクエストを送信し、本人確認情報の変更チェック設定を有効または無効にします。

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

POST本文

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

本人確認情報のチェックを有効にするには、<ENABLE_IDENTITY_KEY_CHECK>をtrueに、無効にするにはfalseに設定します。

有効にするためのリクエストの例

curl 'https://graph.facebook.com/v21.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

有効に設定したときの応答の例

{
  "success": true
}

チェックを行った場合の送信メッセージの例

この例では、recipient_identity_key_hashのハッシュ値が顧客の現在のハッシュと一致した場合にのみメッセージが配信されます。

curl 'https://graph.facebook.com/v21.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

受信メッセージWebhookの例

受信メッセージWebhooksでは、顧客のハッシュはidentity_key_hashプロパティに割り当てられます。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

配信ステータスWebhookの例

配信ステータスWebhooksでは、顧客のハッシュはrecipient_identity_key_hashプロパティに割り当てられます。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

配信に失敗した場合の配信ステータスWebhookの例

配信ステータスWebhooksでは、顧客のハッシュはrecipient_identity_key_hashプロパティに割り当てられます。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

スループットレベルの取得

WhatsApp Business電話番号エンドポイントを使って、電話番号の現在のスループットレベルを取得します。

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput