跳转到主要内容
通过自定义应用,你可以为集成授予对指定 WhatsApp Business 电话号码和 YCloud API 的访问权限。每个应用都拥有独立的 API Key、API 权限和 Webhook 配置。 如果你希望将集成限制在其所需的资产和功能范围内,请使用自定义应用。

开始之前

请确保:
  • 你的账户使用的是 YCloud 付费套餐。免费套餐不支持自定义应用。
  • 你的角色可以访问 YCloud 控制台中的 Developers > Custom apps 。
  • 应用所需的 WhatsApp Business 电话号码已添加到你的 YCloud 账户中。
  • 你已清楚该集成所需的 API 权限。
  • 如果应用需要接收 Webhook 事件,你需要准备一个可公开访问的 HTTPS 端点。
请将应用的 API Key 和 Webhook 签名密钥存放在机密管理器中。切勿在客户端代码、日志、屏幕截图或源码版本控制中泄露它们。

创建应用

  1. 登录 YCloud 控制台。
  2. 前往 Developers > Custom apps。
  3. 点击 Create app。
YCloud 控制台中的自定义应用页面,包含“创建应用”按钮。
  1. 输入 App name。名称最多可包含 64 个字符。
  2. 可选:输入最多 512 个字符的 Description ,以便你的团队了解该应用的用途。
  3. 点击 Create。
包含“应用名称”和“描述”字段的“创建应用”对话框。

Enter an app name and, optionally, a description before selecting Create.

YCloud 会为该应用分配一个只读的应用 ID。新应用默认处于停用状态,直到你明确将其启用。在启用之前,请配置好其资产、API 访问权限和 Webhook 事件。

分配 WhatsApp 电话号码

仅分配该集成需要访问的电话号码。
  1. 打开应用并选择 Assets。
  2. 点击 Add phone numbers。
自定义应用的“资产”部分,包含“添加电话号码”按钮。
  1. 通过业务管理平台名称、WABA ID、WABA 名称或电话号码查找号码。
  2. 选择一个或多个 WhatsApp Business 电话号码。
  3. 点击 Confirm。
选择窗口还会显示每个号码的绑定状态和质量评级(如果该信息可用)。
“添加电话号码”对话框,显示可用的 WhatsApp Business 电话号码、绑定状态和质量评级。
所选号码现在会显示在应用的资产列表中。

配置 API Key 和权限

YCloud 会在 API key & permissions 中显示应用的 API Key。自定义应用 Key 以 yc_ak_ 开头。使用复制操作安全地存储该 Key,然后仅添加该集成所需的权限。
自定义应用的“API Key 与权限”部分。
  1. 选择 API key & permissions。
  2. 在 API permissions 下,点击 Add permissions。
  3. 按分类筛选,或按权限名称或范围进行搜索。
  4. 选择各项所需权限。例如,联系人权限细分为读取、创建或更新以及删除范围。
  5. 点击 Confirm。
“编辑权限”对话框,显示联系人权限范围。
在 X-API-Key 请求头中发送生成的 Key,并仅在受信任的服务端代码中使用它。YCloud 会检查该应用是否处于激活状态,以及请求是否与为其选定的某个 API 权限相匹配。当 API 对 WhatsApp 资产进行操作时,YCloud 还会验证该应用是否具有访问相应电话号码或 WABA 的权限。 并非所有 YCloud API 都向自定义应用开放。未在权限选择器中列出的 API 将对自定义应用 Key 拒绝访问。此外,自定义应用 Key 不能与 X-Managed-Account-ID 请求头结合使用。 有关请求头和凭据处理的指导,请参阅 Authentication。
API Key 部分包含用于重新生成 Key 的操作。根据你在重新生成时选择的选项,旧 Key 会立即失效,或者在 1 小时的过渡期内保持可用。请在过渡期结束前更新所有使用该 Key 的服务。

配置 Webhook

为此应用所需的事件配置专用接收目标。应用 Webhook 与在 Developers > Webhooks 下配置的 Webhook 端点是相互独立的。
  1. 选择 Webhook。
  2. 在 Endpoint URL 中输入你的公开 HTTPS 端点并保存。
  3. 安全存储生成的 Signing secret 。
  4. 在 Added events 下,点击 Add events。
Webhook 部分,包含“端点 URL”、“签名密钥”和“已添加的事件”设置。
  1. 按分类筛选,或按事件名称或事件类型进行搜索。
  2. 选择你的端点必须接收的事件。
  3. 如果某个事件提供数据范围选项,请选择与你的集成相符的范围。
  4. 点击 Confirm。
“添加 Webhook 事件”对话框,显示可用的联系人事件。
YCloud 仅将选定的事件传递到活跃的应用端点。WhatsApp 事件会根据应用分配的电话号码或其所属的 WABA 进行筛选。针对特定事件的数据范围设置可以进一步将事件传递限制为归属于该应用的数据。联系人和退订事件属于租户级别,因为它们未与 WhatsApp 资产相关联。 您的端点在处理请求前应先验证 YCloud 签名,并及时返回成功的 2xx 响应。有关签名验证、事件传递处理和安全指南,请参阅配置 Webhook。有关事件架构,请参阅Webhook 事件负载。

启用并验证应用

在生产环境中使用该应用之前:
  1. 确认该应用包含预期的 WhatsApp Business 电话号码。
  2. 检查每项 API 权限,并移除集成不需要的访问权限。
  3. 返回 开发者 > 自定义应用 ,并在其操作菜单中启用该应用。
自定义应用列表,显示未激活应用的操作“启用”。
  1. 确认应用状态为 Active。
  2. 从安全的服务器端环境使用应用 API Key 发送测试请求。
  3. 触发选定的事件,并确认您的端点能够对其进行验证和处理。
只有处于活跃状态的应用才能验证 API 请求或接收 Webhook 事件。您可以通过名称或应用 ID 查找现有应用。打开 编辑 以检查或更新其配置。