云端 API

WhatsApp Business 开放平台 > 云端 API

概览

通过由 Meta 托管的云端 API，大中型企业可与客户开展大规模通信。企业可使用此 API 来构建系统，将数以千计的客户与客服人员或智能助手连接起来，实现程序化交流和人工交流。此外，企业还可将此 API 与众多后端系统集成，如 CRM 和营销平台。

HTTP 协议

云端 API 基于图谱 API 而构建，因此请求使用 HTTP 协议以及网址参数、标头和请求正文的组合来表示。例如，通过基于 UNIX 的命令行对云端 API 发出的常见调用如以下所示：

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

如果您不熟悉图谱 API，请先阅读我们的图谱 API 文档，了解其基础知识。图谱 API 与云端 API 的主要区别在于您通常会使用的访问口令类型、资源权限、请求语法和 Webhooks 语法。云端 API 文档集的相关部分中对这些区别作出了详细描述。

资源

使用此 API 时，您会与以下主要资源进行互动。

业务资产组合

如要使用此 API，您必须拥有一个业务资产组合。如果您没有，在我们的入门流程中，系统会提示您创建这样一个组合。业务资产组合将成为您 WhatsApp Business 商业帐号 (WABA) 和商家电话号码的一个容器。

如要详细了解业务资产组合，请参阅我们的帮助中心文章关于 Meta Business Suite 中的业务资产组合。

WhatsApp Business 商业帐号

一个 WhatsApp Business 商业帐号代表 WhatsApp Business 开放平台上的一个商家，它主要由一个特定商家的元数据组成。大多数其他 WhatsApp 资源（例如 WhatsApp Business 电话号码和 WhatsApp 消息模板）都与一个 WABA 关联。

您可以按照我们开始文档中的步骤创建一个 WABA。如要详细了解 WABA 及其限制，请参阅 WhatsApp Business 商业帐号。

WhatsApp Business 电话号码

WhatsApp Business 电话号码（公司电话号码）是真实的电话号码。注册用于云端 API 之后，该电话号码即可用来通过此 API 与 WhatsApp 用户相互收发消息。

公司电话号码主要由与该号码本身和您企业相关的元数据组成。当用户与您的公司电话号码互动时，这些元数据可以在出现 WhatsApp 客户端中。

您可以按照我们新手入门文档中的步骤创建一个公司电话号码。请注意，公司电话号码及其使用受到一些限制。我们的公司电话号码文档中对此作出了详细描述。

WhatsApp 消息模板

WhatsApp 消息模板是可定制的模板，可通过此 API 使用各种模板组件进行构建。系统会在这类模板创建就绪后自动对其进行审核；如果获批，即可在模板消息中使用。

通过此 API 可发送两种基本类型的消息：自由格式的消息和模板消息。其中，模板消息因需要使用经批准的 WhatsApp 消息模板，而最受限制。但是，由于模板必须经过审核和批准才能使用，模板消息收到收信人负面反馈的可能性较小，而收信人的负面反馈会完全损害您向客户发送消息的能力。

如要详细了解模板，请参阅我们的模板文档。

Webhooks

Webooks 只是使用 HTTP 协议发送到您服务器上某个公共端点的 JSON 负载。云端 API 在很大程度上依赖于 Webhooks，因为从 WhatsApp 用户发送到您公司电话号码的任何消息内容都会作为 Webhooks 而发出，而且所有传出消息接收状态更新都是通过 Webhooks 来报告。

请注意，我们提供了一个 Webhooks 应用示例，可供您在 Glitch 上克隆和用于测试。该应用只是将 Webhooks 负载直接转存到控制台，可供您查看 Webhooks 的内容。请记住，您最终需要在自己服务器上的某个位置构建自己的端点，以便根据您自己的业务逻辑来消化 Webhooks。

请参阅 Meta Webhooks，详细了解 Webhooks 及其消化方式；另请参阅我们的适用于 WhatsApp Business 商业帐号的 Webhooks 文档。

测试资源

您首次完成我们新手入门文档中的步骤时，系统会自动为您创建一个测试 WABA 和一个测试公司电话号码。

测试 WABA 和测试电话号码对测试很实用，因为它们规避了大多数消息限制，不需要将支付方式存档即可发送模板消息。

在以下情况下，您可以删除自己的业务资产组合及其测试资源：

  • 您是与相关应用关联的业务资产组合的管理员
  • 没有其他应用与该业务资产组合关联
  • 该业务资产组合未关联任何其他 WABA
  • 该 WABA 未关联任何其他商家电话号码。

如要删除您的业务资产组合及其测试资源，请执行以下操作：

  1. 前往应用面板 > WhatsApp > 配置窗口。
  2. 找到测试账户版块。
  3. 点击删除按钮。

身份验证和授权

访问口令

API 支持以下三种口令：

  • 系统用户访问口令
  • 业务集成工具系统用户访问口令
  • 用户访问口令

请参阅我们的访问口令文档，确定您应该使用哪种口令。请注意，应该通过请求标头来传递口令，而不是通过查询字符串参数来传递。

权限

API 依赖以下图谱 API 权限。应用所需要的确切权限组合，取决于应用将访问的端点。

  • business_management — 在与业务资产组合互动时需要。
  • whatsapp_business_management — 在与 WABA 及其分析数据互动或与 WABA 的任意模板或商家电话号码互动时需要。
  • whatsapp_business_messaging — 在与 WhatsApp 用户相互收发消息时需要。

这些权限通常在在 Meta Business Suite 中生成访问口令时授予。请参阅我们访问口令文档中的口令生成相关部分。

版本管理

版本管理使用图谱 API 的版本管理协议。这表示所有端点请求都可以包含一个版本号，且每个版本大约可用 2 年，然后将停用并无法再受到调用。

吞吐量

在默认情况下，对于每个已注册的公司电话号码，云端 API 支持的每秒收发消息总量 (mps) 最多为 80 条，但企业可通过自动升级将此上限提升至 1,000 条。

吞吐量包括入站和出站消息以及所有消息类型。请注意，无论吞吐量如何，公司电话号码仍受其 WhatsApp Business 商业帐号的商家用例流量限制和模板消息限制的约束。

如果您尝试发送的消息数量超过您当前允许的吞吐量级别，API 将返回错误代码 130429，直到您回到允许的吞吐量级别范围内。另外，吞吐量级别专用于涉及不同 WhatsApp 用户电话号码的消息类营销活动。如果您尝试向同一个 WhatsApp 用户号码发送太多消息，可能会遇到配对流量限制错误（错误代码为 131056）。

提高吞吐量

如果您符合我们的资格要求，我们会自动将您的公司电话号码升级至 1,000 mps，无需您支付任何费用。提高吞吐量不会产生额外费用，也不会影响定价。

升级过程本身最多需要 1 分钟。在此期间，该号码将无法在我们的平台上使用。如果在 API 请求中使用，API 将返回错误代码 131057。商家电话号码升级后，未来会自动升级（无停机时间），以应对日后的吞吐量提升。

资格要求

Webhooks

您的 Webhooks 服务器应能够承受 3 倍传出消息流量和 1 倍预期传入消息流量。例如，如果消息发送量为 1,000 mps，且预期回复率为 30%，则您的服务器最多应能处理 3,000 个消息状态 Webhooks 以及 300 个传入消息 Webhooks。

我们会尝试同时发送 Webhooks，因此建议您将 Webhooks 服务器配置为使用以下延迟标准处理并发请求，并对其进行负载测试：

  • 延迟时间中位数不超过 250 毫秒。
  • 超过 1 秒的延迟少于 1%。

我们将根据指数退避算法尝试重新发送失败的 Webhooks，尝试时间最长可达 7 天。

媒体消息

为充分利用更高的吞吐量，建议您将自己的媒体素材上传到我们的服务器，并在媒体消息中使用返回的媒体编号，而不要将这些素材托管到您自己的服务器上并使用这些媒体素材的网址。如果您更想（或必须）在自己的服务器上托管这些素材，建议您使用媒体缓存。

获取吞吐量级别

使用 WhatsApp Business 电话号码端点可获取电话号码当前的吞吐量级别：

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

迁移

如果您从本地 API 迁移公司电话号码至云端 API，当该电话号码具有运行 2 个或以上分片的多连接时，该号码将自动升级至更高吞吐量。

流量限制

每个 WABA 都有 API 调用次数流量限制。您的应用每次向 WABA 的任意公司电话号码（即 WhatsApp Business 电话号码节点或其任意连线，例如消息端点）发出的 API 调用都会计入此限制。

当前限制为：给定 WABA 在连续 1 小时内的 API 调用次数为 11,880,000 次。

例如，在一个小时内，您的应用可以在与WABA A 关联的 WhatsApp Business 电话号码上发出 1,188 万次 API 调用，并在与WABA B 关联的 WhatsApp Business 电话号码上另外进行 1,188 万次 API 调用。或者，在一个小时内，您的应用可以在与单个 WABA 关联的不同 WhatsApp Business 电话号码组合上进行最多 1,188 万次 API 调用。

如果您达到限制，API 将回复错误代码80007。

请注意，WhatsApp Business 管理 API 具有不同的流量限制。请参阅 WhatsApp Business 管理 API 流量限制。

除了这些流量限制，我们对模板消息和测试公司电话号码等单个资源还具有更细化的限制：

可用指标

作为云端 API 用户，您可以查看已发送且已送达的消息数量，以及其他指标。详情请参阅获取帐号指标。

扩展

在 Meta 的基础架构中，云端 API 会在您的流量限制（WABA 的消息量和数量）范围内自动扩展并调整，以处理您的工作负载。

数据隐私和安全

详情请参阅我们的隐私和安全概览。

加密

使用云端 API，每条 WhatsApp 消息在离开设备之前，都会持续受到 Signal 协议加密的保护。这意味着系统会将使用 WABA 发送的消息安全地发送至每个企业选择的目标位置。

云端 API 使用业界标准加密技术来保护传输中的数据和静态数据。此 API 使用图谱 API 来发送消息，使用 Webhooks 来接收事件，两者均采用业界标准 HTTPS 运作，受 TLS 保护。如需了解更多详情，请参阅我们的“加密概览”白皮书。

如需了解更多详情，请参阅我们的“加密概览”白皮书。

工具

WhatsApp 管理工具

WhatsApp 管理工具是我们的网络应用，支持您手动管理 WhatsApp 资源（如 WABA、公司电话号码和模板），和轻松查看对这些资源的成效分析和质量评级或限制。WhatsApp 管理工具提供的大多数功能也可通过 API 获得，仅几个小功能除外。

您可以通过多种方式访问 WhatsApp 管理工具。每种方式都假设您已完成我们入门指南文档中的所有步骤。

通过 Meta Business Suite

  1. 登录 Meta Business Suite。
  2. 如果您有多个业务资产组合，请使用左侧下拉菜单选择拥有或有权访问您希望在 WhatsApp 管理工具中加载的 WABA 的账户。
  3. 在左侧菜单中，前往帐号 > WhatsApp 帐号。
  4. 选择所需 WABA。
  5. 在摘要选项卡中，点击 WhatsApp 管理工具按钮。

通过应用面板

  1. 前往我的应用。
  2. 选择要在 WhatsApp 管理工具中加载的 WABA 所关联的应用。
  3. 在左侧菜单中，前往 WhatsApp > 快速入门。
  4. 点击 WhatsApp Business 部分中的帐号信息窗口。

通过网址

通过访问以下网址，可直接前往 WhatsApp 管理工具概览，其中显示了给定业务资产组合所拥有的或与该业务资产组合共享的所有 WABA：

https://business.facebook.com/wa/manage/home/

默认情况下，该概览页面会加载您最近创建或被授予访问权限的 WABA，但您可以使用左侧下拉菜单选择包含您要尝试访问的 WABA 的业务资产组合。但是，此操作会带您离开概览页面，然后您必须使用左侧菜单并前往帐号 > WhatsApp 帐号 >（选择所需的 WABA）> 设置 > WhatsApp 管理工具（按钮）。

或者，如果您有多个业务资产组合，可在网址末尾附加一个帐号的编号，并将其加入书签，以更便于访问：

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

在我们的 WhatsApp Business 开放平台工作区，有一个云端 API Postman 收藏夹，其中包含了常见的查询。