开始之前
请确保:- 你的账户使用的是 YCloud 付费套餐。免费套餐不支持自定义应用。
- 你的角色可以访问 YCloud 控制台中的 Developers > Custom apps 。
- 应用所需的 WhatsApp Business 电话号码已添加到你的 YCloud 账户中。
- 你已清楚该集成所需的 API 权限。
- 如果应用需要接收 Webhook 事件,你需要准备一个可公开访问的 HTTPS 端点。
创建应用
- 登录 YCloud 控制台。
- 前往 Developers > Custom apps。
- 点击 Create app。

- 输入 App name。名称最多可包含 64 个字符。
- 可选:输入最多 512 个字符的 Description ,以便你的团队了解该应用的用途。
- 点击 Create。

Enter an app name and, optionally, a description before selecting Create.
分配 WhatsApp 电话号码
仅分配该集成需要访问的电话号码。- 打开应用并选择 Assets。
- 点击 Add phone numbers。

- 通过业务管理平台名称、WABA ID、WABA 名称或电话号码查找号码。
- 选择一个或多个 WhatsApp Business 电话号码。
- 点击 Confirm。

配置 API Key 和权限
YCloud 会在 API key & permissions 中显示应用的 API Key。自定义应用 Key 以yc_ak_ 开头。使用复制操作安全地存储该 Key,然后仅添加该集成所需的权限。

- 选择 API key & permissions。
- 在 API permissions 下,点击 Add permissions。
- 按分类筛选,或按权限名称或范围进行搜索。
- 选择各项所需权限。例如,联系人权限细分为读取、创建或更新以及删除范围。
- 点击 Confirm。

X-API-Key 请求头中发送生成的 Key,并仅在受信任的服务端代码中使用它。YCloud 会检查该应用是否处于激活状态,以及请求是否与为其选定的某个 API 权限相匹配。当 API 对 WhatsApp 资产进行操作时,YCloud 还会验证该应用是否具有访问相应电话号码或 WABA 的权限。
并非所有 YCloud API 都向自定义应用开放。未在权限选择器中列出的 API 将对自定义应用 Key 拒绝访问。此外,自定义应用 Key 不能与 X-Managed-Account-ID 请求头结合使用。
有关请求头和凭据处理的指导,请参阅 Authentication。
配置 Webhook
为此应用所需的事件配置专用接收目标。应用 Webhook 与在 Developers > Webhooks 下配置的 Webhook 端点是相互独立的。- 选择 Webhook。
- 在 Endpoint URL 中输入你的公开 HTTPS 端点并保存。
- 安全存储生成的 Signing secret 。
- 在 Added events 下,点击 Add events。

- 按分类筛选,或按事件名称或事件类型进行搜索。
- 选择你的端点必须接收的事件。
- 如果某个事件提供数据范围选项,请选择与你的集成相符的范围。
- 点击 Confirm。

2xx 响应。有关签名验证、事件传递处理和安全指南,请参阅配置 Webhook。有关事件架构,请参阅Webhook 事件负载。
启用并验证应用
在生产环境中使用该应用之前:- 确认该应用包含预期的 WhatsApp Business 电话号码。
- 检查每项 API 权限,并移除集成不需要的访问权限。
- 返回 开发者 > 自定义应用 ,并在其操作菜单中启用该应用。

- 确认应用状态为 Active。
- 从安全的服务器端环境使用应用 API Key 发送测试请求。
- 触发选定的事件,并确认您的端点能够对其进行验证和处理。

