WhatsApp Business 开放平台

预验证电话号码

本文档介绍如何在新的嵌入式注册流程中为您的最终客户提供预验证公司电话号码。预验证公司电话号码是您已验证过的公司电话号码，可让最终客户无需再联系您获取一次性密码。

Screenshot of pre-verifed phone numbers in Embedded Signup flow

请注意，预验证公司电话号码由 WhatsApp Business 预验证电话号码对象（临时对象）表示。当最终客户选择其中一个号码并完成新的嵌入式注册流程时，该临时对象会被替换为 WhatsApp Business 电话号码对象。您必须获取该新对象的编号，才能注册该电话号码。

要求

限制

  • 仅适用于新的嵌入式注册流程。请参阅嵌入注册流程文档，了解如何实现该新流程。
  • 您需要负责追踪认领了预验证公司电话号码的客户。
  • 如果在验证后 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": "<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 预验证电话号码 > 请求代码端点，通过短信或语音方式为新创建的预验证公司电话号码请求获取一次性密码。

请求语法

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

响应

若请求成功，API 将返回 true。

{
  "success": <SUCCESS>
}

此外，我们还会向该电话号码发送包含一次性密码的短信或语音信息。请记录该一次性密码，以便在后续请求中使用。

一次性密码短信语法

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
}

一次性密码短信示例

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 将被设为 VERIFIED，有效期为 90 天。

{
  "success": <SUCCESS>
}

请求示例

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

响应示例

{
  "success": true
}

请参阅 WhatsApp Business 预验证电话号码 > 验证代码端点参考文档，了解支持的查询参数。

在拥有一个（或一组）处于已验证状态的预验证公司电话号码后，您可在新的嵌入式注册流程中显示该（这些）电话号码。

在嵌入式注册流程中显示预验证号码

您可以通过预先填好的表单数据，在新的嵌入式注册流程中显示预验证公司电话号码。为此，请在 setup 对象中添加一个 preVerifiedPhone 对象（包含 ids 属性），并将预验证公司电话号码的编号以字符串数组的形式分配到 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 Business 预验证电话号码端点，读取 code_verification_time 和 verification_expiry_time 字段（这两个字段分别表示最近验证时间和验证过期时间）。

确定电话号码是否在嵌入式注册流程中被认领

请参阅获取已认领的电话号码编号部分。

获取已认领的电话号码编号

在 WhatsApp Business 商业帐号 > 电话号码端点上执行 GET 请求，该端点将返回特定 WhatsApp Business 商业帐号上的所有 WhatsApp Business 电话号码。

为一组结果中返回的每个对象解析 display_phone_number 属性。如果某个对象的 display_phone_number 值显示电话号码（例如 16505551234），则表示该对象已被认领。请复制该对象的 id 属性值，因为这是现在表示该电话号码的新 WhatsApp Business 电话号码对象的编号（旧编号将不再有效）。

或者，您可以使用包含 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。如果您要共享，请将新共享的预验证号码告知业务合作伙伴，并向其提供该号码的编号。如果您要取消共享，该号码将不再出现在合作伙伴实现的嵌入式注册流程中。

{
  "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 步中使用预验证公司电话号码的编号，然后跳到第 4 步。

请求语法

使用此请求在 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>

字符串

必要。


预验证公司电话号码的编号。

6635066806614622

<COUNTRY_DIAL_CODE>

字符串

必要。


预验证公司电话号码的国家/地区拨打代码。

1

<DISPLAY_PHONE_NUMBER>

字符串

必要。


预验证公司电话号码的显示电话号码。

5550783881

<VERIFIED_NAME>

字符串

必要。


预验证公司电话号码的显示名。

Lucky Shrub

响应语法

若请求成功，API 响应中将包含 WhatsApp Business 电话号码的编号。使用此编号注册此电话号码（注册电话号码文档中的第 4 步）。

{
  "id": "<ID>"
}

响应属性

占位符描述示例值

<ID>

WhatsApp Business 电话号码的编号。


此对象将替换 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"
}