手機號碼

本指南介紹雲端 API 所用手機號碼的驗證方法及其格式設定要求。

可以加到 WhatsApp Business 帳戶（WABA）的手機號碼設有條件限制。請參閱手機號碼以了解更多。

部分所列 API 呼叫要求您知道自己手機號碼的編號。請參閱取得所有手機號碼以了解如何取得與您 WhatsApp Business 帳戶連結的手機號碼。API 呼叫回應包含與您 WhatsApp Business 帳戶連結的每個手機號碼之編號。儲存您在發出 /PHONE_NUMBER_ID 呼叫時要使用的手機號碼編號。

驗證手機號碼

您需要驗證向顧客傳送訊息時要使用的手機號碼。手機號碼必須透過短訊／語音通話傳送的驗證碼驗證。驗證程序可以透過下方指定的 Graph API 呼叫完成。

如要使用 Graph 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 中執行的操作被我們視為身分有所變更，我們便會為該用戶產生新的身分雜湊值。您可以在商家手機號碼上啟用身分變更檢查設定，這樣無論您什麼時候向顧客傳送訊息，都可以獲取此雜湊值。一旦啟用此設定，每當顧客向您傳送訊息或您向沒有身分雜湊值的顧客傳送訊息時，我們都會在任何傳入訊息 Webhooks 或傳送狀態 Webhooks 中加入顧客的雜湊值。隨後您便可獲取並儲存此雜湊值，以備日後使用。

如要使用此雜湊值，請將其加入傳送訊息要求中。我們會比較要求中的雜湊值與顧客目前的雜湊值。如果兩個雜湊值一致，我們便會將訊息傳送給顧客。如果兩個雜湊值有出入，則表示顧客在您上次向其傳送訊息後身分有所變更，我們將不會向顧客傳送訊息。我們會改為向您傳送包含錯誤代碼 137000 的訊息狀態 Webhooks，通知您訊息傳送失敗以及雜湊值有所出入。

當您收到 Webhooks 表示雜湊值有所出入時，可以假設顧客的手機號碼不再可靠。如要再次確保顧客的手機號碼資料可靠，請使用其他非 WhatsApp 渠道再次驗證顧客身分。一旦再次確保顧客的手機號碼資料可靠後，請將之前傳送失敗的訊息重新傳送到的新身分（如有），且不要在當中加入雜湊值。然後，將訊息傳送狀態 Webhooks 中顯示的顧客新雜湊值儲存好。

要求語法

向 WhatsApp Business 手機號碼 > 設定端點傳送 POST 要求，以啟用或停用身分變更檢查設定。

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

帖子內文

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

將 <ENABLE_IDENTITY_KEY_CHECK> 設為 true 以啟用身分檢查功能，或設為 false 以停用此功能。

啟用要求範例

curl 'https://graph.facebook.com/v19.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/v19.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... "
    }
}'

傳入訊息 Webhooks 範例

在傳入訊息 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"
        }
      ]
    }
  ]
}

傳送狀態 Webhooks 範例

在傳送狀態 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"
        }
      ]
    }
  ]
}

傳送失敗狀態 Webhooks 範例

在傳送狀態 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