whatsapp-flows

WhatsApp Flow 管理

使用时机

使用此技能端到端管理 WhatsApp Flows：发现 Flow、通过版本编辑 Flow JSON、发布/测试、附加数据端点，以及检查响应/日志。

设置

环境变量：

• KAPSO_API_BASE_URL（仅主机名，不含 /platform/v1）
• KAPSO_API_KEY
• META_GRAPH_VERSION（可选，默认值为 v24.0）

使用 Node 或 Bun 运行脚本：

node scripts/list-flows.js

使用方法

创建并发布 Flow

1. 创建 Flow：node scripts/create-flow.js --phone-number-id <id> --name <name>
2. 阅读 references/whatsapp-flows-spec.md，了解 Flow JSON 规则
3. 更新 JSON：node scripts/update-flow-json.js --flow-id <id> --json-file <path>
4. 发布：node scripts/publish-flow.js --flow-id <id>
5. 测试：node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>

附加数据端点（动态 Flow）

1. 设置加密：node scripts/setup-encryption.js --flow-id <id>
2. 创建端点：node scripts/set-data-endpoint.js --flow-id <id> --code-file <path>
3. 部署：node scripts/deploy-data-endpoint.js --flow-id <id>
4. 注册：node scripts/register-data-endpoint.js --flow-id <id>

调试 Flow

• 列出响应：node scripts/list-flow-responses.js --flow-id <id>
• 函数日志：node scripts/list-function-logs.js --flow-id <id>
• 函数调用：node scripts/list-function-invocations.js --flow-id <id>

Flow JSON 规则

静态 Flow（无数据端点）：

• 使用 version: "7.3"
• routing_model 和 data_api_version 为可选项
• 参见 assets/sample-flow.json

动态 Flow（带数据端点）：

• 使用 version: "7.3" 和 data_api_version: "3.0"
• routing_model 必填，用于定义有效的屏幕跳转
• 参见 assets/dynamic-flow.json

编辑前请阅读 references/whatsapp-flows-spec.md 中的完整规范。

数据端点规则

处理程序签名：

async function handler(request, env) {
  const body = await request.json();
  // body.data_exchange.action: INIT | data_exchange | BACK
  // body.data_exchange.screen: current screen id
  // body.data_exchange.data: user inputs
  return Response.json({
    version: "3.0",
    screen: "NEXT_SCREEN_ID",
    data: { ... }
  });
}

• 不要使用 export 或 module.exports
• 完成时使用 screen: "SUCCESS" 和 extension_message_response.params
• 不要包含 endpoint_uri 或 data_channel_uri（Kapso 会注入这些参数）

脚本

Platform API

脚本	用途
list-flows.js	列出所有 Flow
create-flow.js	创建新 Flow
get-flow.js	获取 Flow 详情
read-flow-json.js	读取 Flow JSON
update-flow-json.js	更新 Flow JSON（创建新版本）
publish-flow.js	发布 Flow
get-data-endpoint.js	获取数据端点配置
set-data-endpoint.js	创建/更新数据端点代码
deploy-data-endpoint.js	部署数据端点
register-data-endpoint.js	向 Meta 注册数据端点
get-encryption-status.js	检查加密状态
setup-encryption.js	设置 Flow 加密

Meta 代理

脚本	用途
send-test-flow.js	发送测试 Flow 消息
delete-flow.js	删除 Flow

日志和响应

脚本	用途
list-flow-responses.js	列出已存储的 Flow 响应
list-function-logs.js	列出函数日志
list-function-invocations.js	列出函数调用

故障排除

• 预览显示“flow_token is missing”：Flow 是未配置数据端点的动态 Flow。请附加数据端点并刷新。
• 加密设置错误：在电话号码/WABA 的设置中启用加密。
• OAuthException 139000 (Integrity)：必须在 Meta 安全中心验证 WABA。

参考资料

• references/whatsapp-flows-spec.md - Flow JSON 规范（编辑前阅读）
• assets/sample-flow.json - 静态 Flow 示例（无端点）
• assets/dynamic-flow.json - 动态 Flow 示例（带端点）

相关技能

• whatsapp-messaging - WhatsApp 消息和模板
• kapso-automation - 工作流自动化
• kapso-api - Platform API 和客户