管理 WhatsApp Flows

功能简介

WhatsApp Flows 是在 WhatsApp 内部运行的多屏幕体验。将其用于结构化任务，例如注册、预约预订、潜客收集、反馈或产品配置。

准备工作

关联将拥有该 Flow 的 WABA。
在有效的 Flow JSON 文档中设计屏幕和数据模型。
确定该 Flow 是否需要数据端点。
选择描述该 Flow 用例的类别。
在验证和预览完成之前，将新内容保留在 DRAFT 状态。

工作原理

创建带有元数据以及可选 JSON 结构的 Flow。
检索 Flow 并修复所有验证错误。
更新元数据或上传修订后的 Flow JSON 文件。
生成公共预览 URL 以供相关人员测试。
当 Flow 准备好用于消息发送时将其发布。
当已发布的 Flow 不再使用时将其废弃。

草稿状态的 Flow 可以编辑或删除。已发布的 Flow 具有更严格的生命周期规则，因此请在发布前进行充分测试。

请求

创建 Flow

POST /whatsapp/flows

curl --request POST https://api.ycloud.com/v2/whatsapp/flows \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wabaId": "WABA_ID",
    "name": "Appointment booking",
    "categories": ["APPOINTMENT_BOOKING"],
    "flowJson": "{\"version\":\"5.0\",\"screens\":[]}",
    "publish": false,
    "endpointUri": "https://example.com/whatsapp/flow"
  }'

更新 Flow 结构

PATCH /whatsapp/flows/{flowId}/assets

curl --request PATCH \
  https://api.ycloud.com/v2/whatsapp/flows/FLOW_ID/assets \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "flowJson=@./flow.json;type=application/json"

预览和发布

使用 GET /whatsapp/flows/{flowId}/preview 生成预览，然后使用 POST /whatsapp/flows/{flowId}/publish 进行发布。

响应

创建操作会返回新的 Flow ID 和操作结果。

{
  "id": "FLOW_ID",
  "success": true
}

检索操作会返回 Flow 的生命周期状态和验证详情。

{
  "id": "FLOW_ID",
  "name": "Appointment booking",
  "status": "DRAFT",
  "categories": ["APPOINTMENT_BOOKING"],
  "validationErrors": []
}

Flow 生命周期

状态	含义
`DRAFT`	该 Flow 可以编辑、验证、预览或删除。
`PUBLISHED`	该 Flow 可以被消息引用。
`DEPRECATED`	该 Flow 不应再用于新的交互。
`BLOCKED` 或 `THROTTLED`	Meta 已限制该 Flow；请检查状态详情。

使用 whatsapp.flow.status_change Webhook 处理异步生命周期更新。

限制与故障排除

将每个验证错误指针视为 Flow JSON 中需要修复的位置。
预览 URL 是公开的；请勿包含生产密钥或敏感测试数据。
发布是生命周期的边界。请先确认内容和端点行为正常。
仅当 Flow 的当前状态允许删除时才可将其删除。
在交换数据时，请对 Flow JSON 和端点行为进行统一版本管理。

创建 Flow API

检查元数据、JSON、克隆和发布选项。

Flow Webhook

处理 Flow 状态变更。

有关健康检查、数据交换、验证和完成响应，请参阅实现 WhatsApp Flow 端点。

开始使用

指南

接口

Webhooks

管理 WhatsApp Flows

功能简介

准备工作

工作原理

请求

创建 Flow

更新 Flow 结构

预览和发布

响应

Flow 生命周期

限制与故障排除

创建 Flow API

Flow Webhook

​功能简介

​准备工作

​工作原理

​请求

​创建 Flow

​更新 Flow 结构

​预览和发布

​响应

​Flow 生命周期

​限制与故障排除

创建 Flow API

Flow Webhook

功能简介

准备工作

工作原理

请求

创建 Flow

更新 Flow 结构

预览和发布

响应

Flow 生命周期

限制与故障排除