从 On-Premises API 迁移到云端 API

本文档介绍了如何将 WhatsApp Business 电话号码从 On-Premises API 迁移到云端 API。

请注意，在不同 API 之间迁移 WhatsApp Business 电话号码的操作与在 WhatsApp Business 商业帐号 (WABA) 之间迁移电话号码的操作不同。

如要从云端 API 迁移到 On-Premises API，请参阅从云端 API 迁移到 On-Premises API。

运作方式

迁移流程涉及生成与 WhatsApp Business 电话号码相关的元数据，然后使用这些数据注册该电话号码，以用于云端 API。相应地，此流程会从 On-Premises API 中注销该电话号码，因为一个电话号码一次只能注册用于一个 API。

迁移不会影响以下项目：

WhatsApp Business 电话号码的显示名、验证状态或质量评分
WhatsApp Business 电话号码使用的模板或模板状态
所属的 WABA、其官方商业帐号状态或其消息限额

但是，为了支持迁移，您必须了解全部 API 差异，并采取适当的操作来应对这些差异，然后再执行本文档中描述的迁移步骤。

要求

Meta 应用

您必须拥有一个 Meta 业务应用，该应用需能够将云端 API 和 WhatsApp Business 管理 API 与已注册客户的数据结合使用，并且能够读取云端 API 和 WhatsApp Business 管理 API Webhooks。该应用还必须与您已认证的 Meta 业务帐户相关联，或由该帐户认领。

如果您没有 Meta 业务应用，或者您有该应用但尚未为其配置 WhatsApp 产品，请完成云端 API 入门指南中的步骤。完成这些步骤后，便可生成测试云端 API 和 WhatsApp Business 管理 API 所需的全部资产。

应用审核

您的 Meta 应用必须经过应用审核并被批准使用（即具备高级访问级别）whatsapp_business_messaging 和 whatsapp_business_management 权限。

最佳实践

确保您的应用可以应对全部 API 差异后，我们建议您首先迁移少量 WhatsApp Business 电话号码，并验证您打算通过云端 API 提供的所有功能是否能够正常运作。验证一切正常后再迁移其他 WhatsApp Business 电话号码。

我们还建议您在 On-Premises API 部署的流量较低时执行迁移。

API 差异

以下 On-Premises API 功能要么不受云端 API 支持，要么就是在云端 API 中的处理方式有所不同。在开始迁移流程前，请确保您的应用能够应对这些差异。

Webhooks

云端 API 和 WhatsApp Business 管理 API 的 Webhooks 负载结构与 On-Premises API 的 Webhooks 负载结构不同。我们建议您新建一个 Webhooks 端点，用于专门处理云端 API 和 WhatsApp Business 管理 API。

请参阅以下文档，帮助您了解负载差异以及如何使用应用面板在应用上配置 Webhooks：

配置：适用于 WhatsApp 的 Webhooks
云端 API Webhooks 负载：Webhooks 通知负载参考文档
WhatsApp Business 管理 API Webhooks 负载：Webhooks 设置

请注意，将 WhatsApp Business 电话号码迁移到云端 API 后，您必须使用 WhatsApp Business 商业帐号 > 已订阅应用端点，为您的 Meta 应用订阅与该 WhatsApp Business 电话号码关联的 WABA 的 Webhooks：

请求语法

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

在您完成迁移至云端 API 的流程后，系统将不再发送该 WhatsApp Business 电话号码的 On-Premises API Webhooks，而是开始发送云端 API Webhooks。

媒体

使用云端 API 发送消息时，无法使用上传到 On-Premises API 的任何媒体的媒体编号，因此您必须使用云端 API 重新上传媒体以生成新的媒体编号；如果媒体托管在公开服务器上，您也可以使用媒体网址。请参阅媒体消息和基于媒体的消息模板。

请注意，为确保消息的诚信，云端 API 不支持 On-Premises API 支持的部分媒体托管网域。如果您为媒体使用托管服务，我们建议您在迁移之前测试自由格式消息和模板消息中的媒体网址。如果您认为自己的托管网域被错误屏蔽，请联系支持团队。

错误代码

云端 API 和 WhatsApp Business 管理 API Webhooks 的错误代码与 On-Premises API 的错误代码不同。请查看以下文档：

属性验证

On-Premises API 可以接受在消息 POST 请求正文负载中使用未知属性，但云端 API 会拒绝此类请求，因此请在您的消息发送请求中仅使用支持的属性。
On-Premises API 允许在仅使用一个按钮发送消息时省略按钮索引，但云端 API 会拒绝此类请求，因此请确保包含按钮的消息发送请求也包含索引及其值。
发送可互动消息时，On-Premises API 接受操作和按钮对象属性中包含开头或末尾空格（或仅空格）的文本字符串，但云端 API 会拒绝此类请求。

“按住即可发言”消息

在 Webhooks 中，On-Premises API 通过将 messages.type 设为 voice 来识别“按住即可发言”（push-to-talk，PTT）消息，而云端 API 通过将 messages.audio.voice 设为 true 来识别此类消息。

贴图包

云端 API 不支持贴图包。

停机时间

在您执行最后的迁移步骤（注册电话号码以用于云端 API）时，停机时间就会开始，并且应该只会持续几秒钟。在此期间，系统会静默删除 WhatsApp 用户发送到该电话号码的消息。

强烈建议您将迁移安排在该电话号码活动较少的时间，以充分降低停机影响。

吞吐量

如果本地 WhatsApp Business 电话号码具有运行 2 个或更多分片的多连接，该电话号码将自动升级为云端 API 的高吞吐量级别。

官方商业帐号

如果您要迁移状态为官方商业帐号 (OBA) 的 Whatsapp Business 电话号码，且您在注册该号码（第 3 步）时在请求中加入了该号码的元数据（在第 2 步中生成），系统将保留该号码的这一状态。如果您没有在请求中加入此数据，该号码将失去 OBA 状态。

迁移支持

如果您在迁移方面有疑问或需要帮助，请按照以下设置，提交站内支持工单：

主题：WABiz：云端 API
请求类型：On-Premises API -> 云端 API 迁移问题

第 1 步：禁用两步验证

如果您知道 WhatsApp Business 电话号码的 PIN 码，则可以跳过这一步。

在执行第 3 步时，您需要用到 WhatsApp Business 电话号码的 PIN 码，因此如果您不知道 PIN 码，则必须首先为该 WhatsApp Business 电话号码禁用两步验证。如果 WhatsApp Business 电话号码并不属于您，您可以要求该电话号码的所有者为您禁用该功能。

第 2 步：生成电话号码元数据

使用备份和恢复 API 生成您 WhatsApp Business 电话号码的相关元数据。

请求语法

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> 可以是任意字符串。该值将用于对元数据进行编码，因此请记录该值，您会在下一步中用到它。

响应

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

API 将返回分配给 data 属性的编码字符串，用于描述您的 WhatsApp Business 电话号码及其设置。请记录该值，您会在下一步中用到它。

<METADATA> — 这是描述您的 WhatsApp Business 电话号码及其设置的编码字符串。请记录该值，您会在下一步中用到它。
<API_STATUS> — 您 On-Premises API 部署的状态。
<API_VERSION> — 您正在运行的 On-Premises API 的版本号。

请求示例

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

响应示例

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

第 3 步：注册电话号码

使用云端 API WhatsApp Business 电话号码 > 注册端点注册电话号码，以用于云端 API。

加入上一步中经过编码处理的 WhatsApp Business 电话号码元数据值和密码。即使没有这些数据，您也可以注册电话号码，但是如果不加入这些数据，WhatsApp Business 电话号码的个人信息数据会丢失，这可能会影响 WhatsApp Business 商业帐号作为官方商业帐号的状态。

请求语法

POST /<BUSINESS_PHONE_NUMBER_ID>/register

POST 请求正文

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> — 现有 PIN 码或您要为 WhatsApp Business 电话号码设置的 PIN 码。
<PASSWORD> — 您在上一步中用于生成 WhatsApp Business 电话号码元数据的密码。
<METADATA> — 描述您在上一步中生成的 WhatsApp Business 电话号码及其设置的编码字符串。

响应

{
  "success": <SUCCESS>
}

如果注册成功，API 会在响应中将 success 设为 true；如果出现错误，则会设为 false。

请求示例

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

响应示例

{
  "success": true
}

第 4 步：查看消息运行状况（可选）

请求 WhatsApp Business 电话号码上的 health_status 字段，并验证该电话号码是否可用于通过云端 API 发送消息。请参阅消息运行状况部分。

WhatsApp Business 开放平台 | 云端 API | 商务管理 API