电话号码

本指南介绍云端 API 中所用电话号码的验证方法及其格式设置要求。

可以添加到 WhatsApp Business 商业帐号 (WABA) 的电话号码有条件限制。请参阅电话号码，了解更多信息。

列出的部分 API 调用要求您知道自己电话号码的编号。请参阅获取所有电话号码，了解如何获取与您的 WABA 关联的电话号码。API 调用响应中包含与您的 WhatsApp Business 商业帐号关联的每个电话号码的编号。保存您在发出 /PHONE_NUMBER_ID 调用时要使用的电话号码编号。

验证电话号码

您需要验证向客户发送消息时要使用的电话号码。必须使用通过短信或语音通话发送的代码验证电话号码。验证流程可以通过下方指定的图谱 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 中执行的操作被我们视为更改了身份，我们会为该用户生成新的身份哈希值。您可以在公司电话号码上启用身份更改检查设置，这样无论您什么时候向客户发送消息，都可以获取该哈希值。一旦启用该设置，当客户向您发送消息或您向没有身份哈希值的客户发送消息时，无论什么时候，我们都会在任何传入消息 Webhooks 或接收状态 Webhooks 中提供客户的哈希值。然后，您可以获取并存储该哈希值，以备将来使用。

如要使用该哈希值，请将其加入发送消息请求中。我们会将该请求中的哈希值与客户当前的哈希值作比较。如果这 2 个哈希值一致，我们便会将消息发送给客户。如果这 2 个哈希值不一致，则表示客户在您上次向其发送消息后更改了身份，我们不会将消息发送给客户。我们会改为向您发送包含错误代码 137000 的消息状态 Webhooks，通知您消息发送失败以及哈希值不一致。

当您收到哈希值不一致 Webhooks 时，会认为客户的电话号码不再可信。如要再次确保客户的电话号码可信，请使用其他非 WhatsApp 渠道再次验证客户身份。您再次确保客户的电话号码可信后，请将之前发送失败的消息重新发送到新身份（如有），而且不要在其中加入哈希值。然后，将消息接收状态 Webhooks 中客户的新哈希值存储好。

请求语法

向 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/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