> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理 WhatsApp Flows

> 创建、验证、预览、发布和废弃结构化的 WhatsApp 体验。

## 功能简介

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

## 准备工作

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

## 工作原理

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

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

## 请求

### 创建 Flow

`POST /whatsapp/flows`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 和操作结果。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "FLOW_ID",
  "success": true
}
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 和端点行为进行统一版本管理。

<CardGroup cols={2}>
  <Card title="创建 Flow API" icon="diagram-project" href="/api-reference/whatsapp-flows/create-a-flow">
    检查元数据、JSON、克隆和发布选项。
  </Card>

  <Card title="Flow Webhook" icon="webhook" href="/zh/api-reference/guides/examples/webhook-examples/whatsapp-flow-webhook-examples">
    处理 Flow 状态变更。
  </Card>
</CardGroup>

有关健康检查、数据交换、验证和完成响应，请参阅 [实现 WhatsApp Flow 端点](/zh/api-reference/guides/whatsapp-platform/implement-a-whatsapp-flow-endpoint)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.