> ## 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 Flow 端点

> 通过 YCloud 处理 Flow 健康检查、错误通知、数据交换、页面导航及完成状态。

当需要动态加载页面或处理 WhatsApp 用户提交的数据时，请使用 Flow 端点。在创建 Flow 或更新其元数据时，将公开的 HTTPS URL 配置为 `endpointUri`。

本指南介绍了 YCloud 转发到您端点的明文 JSON 请求。指南中不涉及与 Meta 加密数据端点的直接连接。有关 Flow 的创建、预览、发布及生命周期管理，请参阅 [管理 WhatsApp Flows](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-flows)。

## 准备工作

* 提供一个接收 `POST` 请求的公开 HTTPS 端点。
* 在 15 秒内返回 JSON 响应。
* 在 Flow JSON 中定义页面及其数据字段。
* 发送 Flow 消息时生成一个 `flow_token`，以便将交互与
  您的应用程序会话进行关联。
* 在接受提交的数据之前进行服务端验证。

## 请求流程

1. 用户在 WhatsApp 中打开 Flow 或与其交互。
2. YCloud 将 JSON 请求转发到您配置的端点。
3. 您的端点读取 `action` 并处理该请求。
4. 您的 JSON 响应选择一个页面并提供其数据，或者完成 Flow。

## 处理健康检查

健康检查包含 `action: ping`：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "action": "ping"
}
```

返回：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "status": "active"
  }
}
```

保持该路径轻量化。切勿在健康检查期间执行业务交易。

## 处理错误通知

错误通知包含 `data.error` 和 `data.error_message`。它们可以使用 `INIT` 或 `data_exchange` 作为操作。在按操作路由常规请求之前，请先检查是否存在此类错误数据。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": "3.0",
  "flow_token": "FLOW_SESSION_TOKEN",
  "action": "data_exchange",
  "data": {
    "error": "ERROR_KEY",
    "error_message": "Error details"
  }
}
```

记录该错误以便排查，并返回确认响应：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "acknowledged": true
  }
}
```

## 处理数据交换

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": "3.0",
  "screen": "DETAILS",
  "action": "data_exchange",
  "data": {
    "email": "customer@example.com"
  },
  "flow_token": "FLOW_SESSION_TOKEN"
}
```

| 字段 | 含义 |
| - | - |
| `version` | 数据 API 版本，在这些请求中为 `3.0`。 |
| `action` | 打开 Flow 时为 `INIT`，提交页面时为 `data_exchange`，返回上一页时为 `BACK`。 |
| `screen` | 当前页面 ID。对于 `INIT` 或 `BACK` 可能不存在。请勿将 Flow 页面命名为 `SUCCESS`；该值已保留用于完成状态。 |
| `data` | 页面字段或提交的输入。对于 `INIT` 或 `BACK` 可能不存在。 |
| `flow_token` | 您在 Flow 消息中提供的会话令牌。 |

根据您定义的页面处理每个操作：

| 操作 | 响应行为 |
| - | - |
| `INIT` | 返回初始页面及其初始数据。 |
| `data_exchange` | 验证提交的数据，然后返回下一个页面或在当前页面返回验证错误。 |
| `BACK` | 返回上一个页面及其所需的数据。 |

### 导航至页面

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "screen": "CONFIRMATION",
  "data": {
    "user_email": "customer@example.com"
  }
}
```

`screen` 必须存在于您的 Flow JSON 中。其声明的数据架构必须能接收 `data` 中的字段。

### 返回验证错误

停留在当前页面，并返回页面所展示的错误字段：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "screen": "DETAILS",
  "data": {
    "error_message": "Please enter a valid email address."
  }
}
```

### 完成 Flow

返回带有 `extension_message_response.params` 的 `screen: SUCCESS`。包含原始的 `flow_token` 以及希望在 Flow 响应消息中附带的任何其他结果字段。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "screen": "SUCCESS",
  "data": {
    "extension_message_response": {
      "params": {
        "flow_token": "FLOW_SESSION_TOKEN",
        "appointment_id": "APPOINTMENT_ID"
      }
    }
  }
}
```

这会关闭 Flow 并向聊天发送一条 Flow 响应消息。从 [入站 Flow 响应 Webhook](/zh/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-interactive-flow-response-message) 中解析该结果。

## 实现示例

此 Express 示例处理了所有三类请求。请将页面 ID 和响应字段与您自己的 Flow JSON 进行匹配。在运行此处理程序之前挂载部署所需的任何端点访问控制。

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import express from "express";

const app = express();
app.use(express.json({ limit: "256kb" }));

app.post("/flow-endpoint", (req, res) => {
  if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
    return res.status(400).json({ error: "Expected a JSON object" });
  }
  const { action, screen, flow_token: flowToken } = req.body;
  const data = req.body.data ?? {};

  if (action === "ping") {
    return res.json({ data: { status: "active" } });
  }
  if (data.error) {
    // Record the error without logging sensitive form data or session tokens.
    return res.json({ data: { acknowledged: true } });
  }
  if (!flowToken) {
    return res.status(400).json({ error: "Missing flow_token" });
  }
  if (action === "INIT" || action === "BACK") {
    return res.json({ screen: "DETAILS", data: {} });
  }
  if (action === "data_exchange" && screen === "DETAILS") {
    if (typeof data.email !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
      return res.json({
        screen: "DETAILS",
        data: { error_message: "Please enter a valid email address." }
      });
    }
    return res.json({ screen: "CONFIRMATION", data: { user_email: data.email } });
  }
  if (action === "data_exchange" && screen === "CONFIRMATION") {
    return res.json({
      screen: "SUCCESS",
      data: { extension_message_response: { params: { flow_token: flowToken } } }
    });
  }
  return res.status(400).json({ error: "Unsupported action or screen" });
});

app.listen(3000);
```

## 验证端点

测试 `ping`、错误确认、不带 `screen` 或 `data` 的 `INIT`、有效和无效的提交、`BACK` 以及 `SUCCESS` 完成情况。检查 15 秒响应限制，并确认完成 Webhook 携带了原始的 `flow_token`。发布 Flow 之前请先进行预览。


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