解决方案合作伙伴入门指南

本指南详细介绍了解决方案合作伙伴为客户提供云端 API 需要采取的步骤。整个流程分为如下 4 个主要阶段：

1. 准备和计划
2. 设置资产
3. 签署合同
4. 构建集成

完成上述步骤后，请保持每月更新。

准备和计划

阅读相关文档

开始之前，建议您通读开发者文档和 Postman 收藏夹。这有助您了解云端 API 的运行原理，包括如何入门和迁移号码。

安排注册和迁移

您必须使用嵌入式注册让新客户开始使用云端 API。如果您尚未执行此步骤，请集成并启动嵌入式注册。嵌入式注册是最快捷简单的客户注册方式，客户只需不到五分钟即可完成注册，开始发送消息。

接下来，请考虑您希望先将哪些客户迁移至云端 API。我们一般建议将所有客户从本地迁移至云端 API，但每位客户的需求可能各不相同。在考虑要迁移哪些客户时，请考虑以下因素：

确定迁移对象后，即可制定迁移计划和时间表。

在制定计划时，记得设计适用于以下两种场景的系统：新客户注册，以及将现有客户从本地迁移到云端 API。对于迁移，请加入相关计划，备份您当前的本地实例并将相关号码迁移到云端 API。

安排与客户的沟通

首先，您需要确定是否要通知现有客户有关迁移的事宜。然后，您应确定是否需要创建或更新任何支持文档，以帮助完成云端 API 设置。

制定定价决策

由于云端 API 的托管费用由 Meta 承担，您需决定是否对您的定价作出相应的更新。

设置资产

如要使用云端 API，解决方案合作伙伴需要准备下列资产：

签署合同

接受服务条款

如要访问 WhatsApp Business 消息云端 API，您首先需要代表您的商家接受《WhatsApp Business 开放平台服务条款》。

为此，请前往 WhatsApp 管理工具并接受信息横幅中的服务条款。

如果您目前是云端 API 的 Beta 测试版合作伙伴，则会有 90 天的宽限期。这表示您需要在 2022 年 7 月 5 日前接受服务条款，否则会失去访问权限。

如果您是新加入云端 API 的商家（包括从本地 API 迁移的商家），则需接受服务条款后才能开始使用云端 API。如不接受服务条款，注册调用会一直失败。

构建集成

第 1 步：获取系统用户访问口令

图谱 API 调用使用访问口令进行身份验证。详情请参阅访问口令。建议您使用系统用户来生成口令。

如要生成系统用户访问口令，请根据下列步骤操作：

1. 转到商务管理平台 > 业务设置 > 用户 > 系统用户，以查看您创建的系统用户。
2. 点击该用户，然后选择添加资产。此操作会启动一个新窗口。
3. 在左侧边面板的选择资产类型下，选择应用。在选择资产下，选择要使用的 Meta 应用（您的应用必须具有正确的权限）。为该应用启用开发应用。
4. 选择保存更改，以保存设置并返回系统用户主屏幕。
5. 现在可以生成口令了。在系统用户主屏幕中，点击生成口令，然后选择您的 Meta 应用。选择应用后，页面即会显示可用权限列表。选择 whatsapp_business_management 和 whatsapp_business_messaging。点击生成口令。
6. 系统随即打开一个新窗口，其中包含您的系统用户、指定的应用和访问口令。保存您的口令。
7. 您可以选择点击该口令并查看口令调试工具。调试工具中会显示您已选择的 2 项权限。您也可以直接将口令粘贴到访问口令调试工具中。

第 2 步：设置 Webhooks

通过 Webhooks 设置，您将可接收 WhatsApp Business 开放平台的实时 HTTP 通知。这表示您会在出现相关动态时收到通知，例如收到客户发来的消息或您的 WhatsApp Business 商业帐号 (WABA) 发生更改。

如要设置 Webhooks，您需要使用符合 Meta 和 WhatsApp 要求的网址，创建面向互联网的网络服务器。如需具体操作说明，请参阅创建端点。如果需要用于测试的端点，您可以生成一个测试 Webhooks 端点。

应用设置

准备好端点后，请配置此端点以供 Meta 应用使用：

您只需为每个应用程序设置一次 Webhooks。您可以使用相同的 Webhooks 接收多个 WhatsApp Business 商业帐号的多个事件类型。详情请参阅我们的 Webhooks 部分。

第 3 步：订阅 WABA

为确保收到正确帐号的通知，请订阅您的应用：

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

如果收到下方响应，此帐号所含电话号码的所有 Webhooks 事件都将发送到您配置的 Webhooks 端点。

{
  "success": true
}

第 4 步：获取电话号码编号

如要发送消息，您需要注册想要使用的电话号码，即上文准备工作中提到的商家电话号码。

在进行注册前，您需要找到该电话号码的编号。如要获取电话号码编号，请作出以下 API 调用：

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

如果请求成功，响应中将包含与您的 WABA 关联的所有电话号码：

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

保存您想注册的电话号码的编号。如需了解此端点的详细信息，请参阅读取电话号码。

迁移例外情况

第 5 步：注册电话号码

获取电话号码编号后，您即可注册该号码。在注册 API 调用中，您需同时执行以下两项操作：

1. 注册电话号码。
2. 启用两步验证功能，设置一个 6 位数注册码（此码必须由您设置）。保存并记住此注册码，以供之后请求时使用。

使用云端 API 必须设置双重验证。如未设置，您将收到一条注册失败消息：

请求示例：

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

响应示例：

{
  "success": true
}

嵌入式注册用户

第 6 步：接收消费者应用的消息

在参与的客户向您的商家发送消息后，您即可获得 24 小时免费消息窗口期，此窗口期称为“客户服务窗口期”。出于测试目的，我们需要启用此窗口期，这样您就可以发送任意数量的消息。

使用个人 WhatsApp iOS/Android 应用向您刚注册的电话号码发送一条消息。发送消息后，您应会收到一条传入 Webhooks 的通知消息，其格式如下。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

第 7 步：发送测试消息

启用客户服务窗口期后，您可以向上一步中使用的消费者号码发送一条测试消息。为此，请作出以下 API 调用：

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

如果调用成功，响应中将包含消息编号。请使用该编号通过 Webhooks 来追踪消息进度。该编号最长为 128 个字符。

响应示例：

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

跟进每月更新

我们将在每个月的第一个星期二发布云端 API 更新。更新包括新功能和改进。云端 API 会自动更新，因此您无需任何操作，即可使用发布的任何新功能。

常见问题

一般常见问题

技术实施常见问题

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

固定链接

数据隐私和安全常见问题

监管合规常见问题