从云端 API 迁移至本地 API

我们将弃用本地 API。请参阅我们的本地 API 弃用文档，了解弃用详情以及如何迁移到我们的下一代云端 API。

本文档介绍了如何将 WhatsApp Business 电话号码从云端 API 迁移到本地 API。如要从本地 API 迁移到云端 API，请参阅从本地 API 迁移到云端 API。

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

迁移不会影响以下项目：

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

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

最佳实践

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

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

API 差异

在开始迁移流程前，请确保您的应用能够应对这些差异。

Webhooks

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

请参考以下文件，帮助您了解负载差异：

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

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

媒体

使用本地 API 发送消息时，无法使用上传到云端 API 的任何媒体的媒体编号，因此您必须使用本地 API 重新上传媒体以生成新的媒体编号；如果媒体托管在公开服务器上，您也可以使用媒体网址。请查看发送媒体消息。

错误代码

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

“按住即可发言”消息

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

停机时间

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

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

第 1 步：集成本地 API

由于您要将公司电话号码迁移至本地 API，请确保您的应用可以成功使用本地 API 客户端，并且与该公司电话号码关联的 WhatsApp Business 商业帐号已正确配置了 Webhooks。

第 2 步：准备迁移

建议您在执行迁移期间停止发送消息。

如要将 WhatsApp Business API 本地客户端连接至 WhatsApp 服务器，需满足一定的网络要求。为确保您做好准备，请查看设置及调试网络文档。

第 3 步：注册 API 客户端

在您的本地 API 客户端上注册公司电话号码。如要注册，请调用 /account 端点：

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

根据收到的响应，我们可以认为注册程序已完成，或需要其他步骤来完成。如果注册成功，您会收到下列 HTTP 状态代码中的一个。请根据您收到的响应执行相应操作：

201 Created — 该帐户已经存在。您已经注册过应用，因此无需进行其他操作。
202 Accepted — 该帐户不存在。请根据您在请求中选择的方式，检查用于接收注册代码的短信或语音通话号码。此响应将包括一个返回的负载，其中包含从 cert 参数解码的 vname，供您确认要设置的显示名称正确无误。如果正确，请继续在完成您的帐户注册部分来完成注册。

点击此处，查看此端点的所有可用字段。

注册完成后，本地 API 客户端便可接收消息。

第 4 步：设置分片

注册客户端后，您便可以根据需要设置分片。

第 5 步：开始发送消息

您已准备好向客户发送消息了。请参阅发送消息指南，获取相关指导。

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