实现 WhatsApp Flow 端点

当需要动态加载页面或处理 WhatsApp 用户提交的数据时，请使用 Flow 端点。在创建 Flow 或更新其元数据时，将公开的 HTTPS URL 配置为 endpointUri。本指南介绍了 YCloud 转发到您端点的明文 JSON 请求。指南中不涉及与 Meta 加密数据端点的直接连接。有关 Flow 的创建、预览、发布及生命周期管理，请参阅管理 WhatsApp Flows。

准备工作

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

请求流程

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

处理健康检查

健康检查包含 action: ping：

{
  "action": "ping"
}

{
  "data": {
    "status": "active"
  }
}

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

处理错误通知

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

{
  "version": "3.0",
  "flow_token": "FLOW_SESSION_TOKEN",
  "action": "data_exchange",
  "data": {
    "error": "ERROR_KEY",
    "error_message": "Error details"
  }
}

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

{
  "data": {
    "acknowledged": true
  }
}

处理数据交换

{
  "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`	返回上一个页面及其所需的数据。

导航至页面

{
  "screen": "CONFIRMATION",
  "data": {
    "user_email": "customer@example.com"
  }
}

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

返回验证错误

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

{
  "screen": "DETAILS",
  "data": {
    "error_message": "Please enter a valid email address."
  }
}

完成 Flow

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

{
  "screen": "SUCCESS",
  "data": {
    "extension_message_response": {
      "params": {
        "flow_token": "FLOW_SESSION_TOKEN",
        "appointment_id": "APPOINTMENT_ID"
      }
    }
  }
}

这会关闭 Flow 并向聊天发送一条 Flow 响应消息。从入站 Flow 响应 Webhook 中解析该结果。

实现示例

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

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 之前请先进行预览。

开始使用

指南

接口

Webhooks

实现 WhatsApp Flow 端点

准备工作

请求流程

处理健康检查

处理错误通知

处理数据交换

导航至页面

返回验证错误

完成 Flow

实现示例

验证端点

​准备工作

​请求流程

​处理健康检查

​处理错误通知

​处理数据交换

​导航至页面

​返回验证错误

​完成 Flow

​实现示例

​验证端点

准备工作

请求流程

处理健康检查

处理错误通知

处理数据交换

导航至页面

返回验证错误

完成 Flow

实现示例

验证端点