WhatsApp Business 管理 API

概览

借助 Business 管理 API，您可创建和管理 WhatsApp 相关的业务资产，如 WhatsApp Business 商业帐号和消息模板。此 API 建立在市场营销 API 基础之上，并利用了后者的一些端点，因此本文档可能会在相应的地方包含指向市场营销 API 文档的链接。

要求

访问口令

该开放平台支持以下访问口令类型。您使用的类型取决于使用您应用的用户，以及您是否是解决方案提供方。

系统用户访问口令

系统用户访问口令代表您、您的企业或组织或者您企业或组织内的用户。这些口令的主要优点是不会过期，相当于您企业中不需要任何用户输入的自动化服务。

系统用户访问口令是解决方案合作伙伴可用来与已注册客户共享额度的唯一一类口令。

必须先创建系统用户，才能生成系统用户访问口令。大多数端点会检查由该口令确定身份的用户是否有权访问所查询的资源。如果用户无权访问该资源，请求将遭到拒绝，并收到错误代码 200。

系统用户可以是工作人员或管理员。

工作人员系统用户

工作人员系统用户必须获得权限授权，才能访问由 Meta 企业拥有的或与该企业共享的各个 WhatsApp Business 商业帐号。如果您的应用仅需访问您拥有的几个 WhatsApp Business 商业帐号，工作人员系统用户应该就足以满足需求。

创建后，您必须向系统用户需要访问的每个 WhatsApp Business 商业帐号授予全部或部分权限。

管理员系统用户

默认情况下，管理员系统用户可完全访问所有 WhatsApp Business 商业帐号以及由您或您企业拥有的或与您或您企业共享的资产。

如果您的应用需要访问最近与您企业共享的 WhatsApp Business 商业帐号，可使用管理员系统用户；如果您使用工作人员系统用户，则必须向已与您共享的每个 WhatsApp Business 商业帐号手动授予访问权限。

请注意，您可以通过向每个 WhatsApp Business 商业帐号授予部分权限，来忽略管理员系统用户的默认访问权限。

创建系统用户

如要创建系统用户，请执行以下操作：

  1. 登录 Meta Business Suite。
  2. 在左上角下拉菜单中找到您的业务帐户，并点击设置（齿轮）图标。
  3. 点击业务设置。
  4. 前往用户 > 系统用户。
  5. 点击添加按钮，创建管理员或工作人员系统用户。

生成系统用户访问口令

创建系统用户之后，如要生成系统用户访问口令，请执行以下操作：

  1. 登录 Meta Business Suite。
  2. 在左上角下拉菜单中找到您的业务帐户，并点击设置（齿轮）图标。
  3. 点击业务设置。
  4. 前往用户 > 系统用户。
  5. 从系统用户列表中选择相应的系统用户。
  6. 点击生成新口令按钮。
  7. 选择将使用此口令的应用。
  8. 选择应用正常运行所需的任何权限，并生成口令。

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

业务集成工具系统用户访问口令的使用范围限定于单个已注册客户。技术代理和解决方案合作伙伴在访问已注册客户的数据时，应使用这类访问口令。

这些口令适用于以下应用：在客户 WhatsApp Business 商业帐号上执行程序化自动操作而无需依赖应用用户输入的应用；或要求将来重新验证身份的应用。

如要生成业务集成工具系统用户访问口令，您必须实现嵌入式注册（使用企业版 Facebook 登录进行配置），并交换在客户完成流程时向您返回的代码。

请参阅嵌入式注册文档和业务集成工具系统用户访问口令文档，详细了解这些口令及其生成方法。

用户访问口令

虽然所有应用开发者都支持且可以使用用户访问口令，但可能仅在您首次使用应用面板发送您的第一条测试消息时才会用到这些口令。但是，在开发应用时，您很可能会切换到系统用户访问口令（如果您是技术代理或解决方案提供方，最终会切换到业务系统用户访问口令）。这是因为用户访问口令很快就会过期，您必须每隔几个小时就要生成一个新口令。

生成用户访问口令有以下几种方法：

  • 访问应用面板 > WhatsApp > API 设置面板。每次您访问时，此面板总会生成新的用户访问口令。该口令会自动将使用范围限定于您的用户，因为您在访问此面板时已登录开发者帐户。
  • 使用图谱 API 探索工具。
  • 实现 Facebook 登录。

在请求中使用口令

在发出 API 请求时，应在授权请求标头中加入您的口令，并在口令前添加前缀 Bearer。例如：

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

WhatsApp Business 商业帐号的访问权限

很多端点要求，在 API 请求中加入口令的用户也必须获得部分或全部权限的授权，才能访问所查询的 WhatsApp Business 商业帐号（或其资产）。如果用户未获授权，API 将返回错误代码 200。

您可以为任何用户（包括系统用户）设置细化权限。如需限制用户群体对特定资产的访问权限，不妨为系统用户设置细化权限。例如，如果您有一个大型企业，让后希望某个部门对某个 WhatsApp Business 商业帐号的模板和公司电话号码数据仅具有读取权限，则可以为该部门创建一个系统用户，并将细化权限设置为仅可查看。

如要指定对 WhatsApp Business 商业帐号或其资产的用户访问权限，请执行以下操作：

  1. 登录 Meta Business Suite。
  2. 在左上角下拉菜单中找到您的业务帐户，并点击设置（齿轮）图标。
  3. 点击业务设置。
  4. 前往帐户 > WhatsApp 帐户。
  5. 选择适当的 WhatsApp Business 商业帐号。
  6. 选择 WhatsApp 帐户访问权限选项卡。
  7. 点击 +添加用户按钮。
  8. 选择适当的系统用户，并分配对 WhatsApp Business 商业帐号的适当访问级别。

测试端点

测试端点时，建议使用我们的 Postman 收藏夹或 cURL。虽然您可以使用图谱 API 探索工具，但该工具会以查询字符串参数的形式来传递口令，我们不建议采用此种方式（建议采用在请求标头中加入口令的传递方式）。

获取企业相关信息

如要获取特定企业的相关信息，请向 WhatsAppBusinessAccount 端点发送 GET 请求，其中，<WHATSAPP_BUSINESS_ACCOUNT_ID> 是您的 WhatsApp Business 商业帐号编号。

请求示例

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

响应示例

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

如要获取某个企业的特定信息（例如名称、消息模板和电话号码），请向 WhatsAppBusinessAccount 端点发送 GET 请求（其中 <WHATSAPP_BUSINESS_ACCOUNT_ID> 是您的 WhatsApp Business 商业帐号编号），并将 fields 参数设置为您希望返回的项目清单。

请求示例

curl -i -X GET 'https://graph.facebook.com/v19.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

响应示例

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

流量限制

系统会根据您应用的调用次数计算该应用向 WhatsApp Business 管理 API 发出的请求次数。应用的调用次数是指该应用在连续一小时内可以发出的调用数量。对于以下 WhatsApp Business 管理 API，您的每个应用每小时默认可以向每个 WhatsApp Business 商业帐号 (WABA) 发出 200 次调用。对于使用正常且至少拥有一个已注册电话号码的 WABA，您的每个应用每小时可以向每个使用正常的 WABA 发出 5,000 次调用。
调用类型 端点

GET

/{whatsapp-business-account-id}

GET、POST 和 DELETE

/{whatsapp-business-account-id}/assigned_users

GET

/{whatsapp-business-account-id}/phone_numbers

GET、POST 和 DELETE

/{whatsapp-business-account-id}/message_templates

GET、POST 和 DELETE

/{whatsapp-business-account-id}/subscribed_apps

GET

/{whatsapp-business-account-to-number-current-status-id}

对于以下额度 API，您的每个应用每小时可以发出 5,000 次调用。
调用类型 端点

GET

/{business-id}/extendedcredits

POST

/{extended-credit-id}/whatsapp_credit_sharing_and_attach

GET 和 DELETE

/{allocation-config-id}

GET

/{extended-credit-id}/owning_credit_allocation_configs

为避免达到流量限制，我们建议使用 Webhooks 来追踪消息模板、电话号码和 WABA 的状态更新。

有关如何获取您当前流量使用情况的更多信息，请参阅标头。

详细了解

后续步骤