Skip to main content
自定义应用允许你为集成授予对指定 WhatsApp Business 电话号码和 YCloud API 的访问权限。每个应用都拥有独立的 API Key、API 权限和 Webhook 配置。 当你希望将集成限制在其所需的资产和功能范围内时，请使用自定义应用。

​
准备工作

请确保：
  • 你的账户使用的是 YCloud 付费方案。免费方案不支持自定义应用。
  • 你的角色可以访问 YCloud 控制台中的 开发者 > 自定义应用 。
  • 应用所需的 WhatsApp Business 电话号码已在你的 YCloud 账户中就绪。
  • 你已清楚该集成需要哪些 API 权限。
  • 如果应用需要 Webhook 事件，你需拥有一个公网可访问的 HTTPS 端点。
请将应用 API Key 和 Webhook 签名密钥妥善保存在机密管理器（Secret Manager）中。切勿在客户端代码、日志、屏幕截图或源代码控制中泄露它们。

​
创建应用

  1. 登录 YCloud 控制台。
  2. 前往 开发者 > 自定义应用。
  3. 点击 创建应用。
YCloud 控制台中的自定义应用页面，包含“创建应用”按钮。
  1. 输入 应用名称。名称最多可包含 64 个字符。
  2. 可选：输入最多 512 个字符的 描述 ，以便你的团队了解该应用的用途。
  3. 点击 创建。
包含“应用名称”和“描述”字段的“创建应用”弹窗。

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

YCloud 会为该应用分配一个只读的应用 ID。新应用在显式启用之前处于禁用状态。在启用之前，请先配置其资产、API 访问权限和 Webhook 事件。

​
分配 WhatsApp 电话号码

仅分配集成需要访问的电话号码。
  1. 打开应用并选择 资产。
  2. 点击 添加电话号码。
自定义应用的资产部分，包含“添加电话号码”按钮。
  1. 通过 Business Manager 名称、WABA ID、WABA 名称或电话号码查找号码。
  2. 选择一个或多个 WhatsApp Business 电话号码。
  3. 点击 确认。
选择窗口还会显示每个号码的绑定状态和质量评级（如果该信息可用）。
显示可用 WhatsApp Business 电话号码、绑定状态和质量评级的“添加电话号码”弹窗。
选中的号码现已显示在应用的资产列表中。

​
配置 API Key 和权限

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

​
配置 Webhook

为此应用所需的事件配置专用目标。应用 Webhook 独立于在 开发者 > Webhook 下配置的 Webhook 端点。
  1. 选择 Webhook。
  2. 在 端点 URL 中输入你的公网 HTTPS 端点并保存。
  3. 安全地存储生成的 签名密钥 。
  4. 在 已添加的事件 下，点击 添加事件。
包含“端点 URL”、“签名密钥”和“已添加的事件”设置的 Webhook 部分。
  1. 按分类筛选或按事件名称/事件类型搜索。
  2. 选择端点必须接收的事件。
  3. 如果某个事件提供数据范围选项，请选择与你的集成相匹配的范围。
  4. 点击 确认。
显示可用联系人事件的“添加 Webhook 事件”弹窗。
YCloud 仅向处于活动状态的应用端点投递选定的事件。WhatsApp 事件会根据分配给该应用的照片号码或其父级 WABA 进行筛选。特定事件的数据范围设置可进一步将投递限制为归属于该应用的数据。联系人和取消订阅事件属于租户级别，因为它们未与 WhatsApp 资产关联。 您的端点应在处理请求之前验证 YCloud 签名，并及时返回成功的 2xx 响应。有关签名验证、投递处理和安全指南，请参阅配置 Webhook。有关事件架构，请参阅Webhook 事件有效负载。

​
启用并验证应用

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