automate-whatsapp

自动化 WhatsApp

适用场景

使用此技能构建和运行 WhatsApp 自动化：工作流的增删改查、图编辑、WhatsApp 和 Project Event 触发器、Project Event 发送、执行、函数管理、webhook 工具和 MCP 工具。

设置

首选方式：

• 安装并完成身份验证的 Kapso CLI（kapso login）
• 编辑工作流和函数时，使用源代码受版本控制的项目，并运行 kapso link、kapso pull、kapso build 和 kapso push
• 编写工作流代码时，使用 @kapso/workflows，并从 workflow.js 或 workflow.ts 导出一个 Workflow 实例

备用方式： 环境变量：

• KAPSO_API_BASE_URL（仅主机名，不含 /platform/v1）
• KAPSO_API_KEY

操作指南

在本地编辑工作流

当用户正在使用本地仓库或可以创建本地仓库时，优先使用此方式。

npm install -g @kapso/cli
npm install --save-dev @kapso/workflows
kapso login
kapso link --project <project-id>
kapso pull

使用 @kapso/workflows 编辑 workflows/<workflow-slug>/workflow.js 或 workflow.ts：

import { START, Workflow } from "@kapso/workflows";

const workflow = new Workflow("inbound-support", {
  name: "Inbound Support",
  status: "draft",
});

workflow.addTrigger({
  type: "inbound_message",
  phoneNumberId: "<phone-number-id>",
});

workflow.addNode(START, {
  position: { x: 100, y: 100 },
});

workflow.addNode("reply", {
  type: "send_text",
  message: "Thanks for reaching out.",
});

workflow.addEdge(START, "reply");

export default workflow;

构建并推送：

kapso build
kapso push --dry-run
kapso push workflow <workflow-slug>

使用 kapso push 推送所有本地函数和工作流。有关仓库布局、源文件行为以及仅编辑 JSON 的说明，请参阅 references/local-workflow-source.md。

首先查找电话号码

首选方式：

1. 检查项目状态：kapso status
2. 列出已连接的号码：kapso whatsapp numbers list --output json
3. 如有需要，解析显示号码：kapso whatsapp numbers resolve --phone-number "<display-number>" --output json

备用方式：

1. 列出触发器的号码配置：node scripts/list-whatsapp-phone-numbers.js

通过 API 脚本编辑工作流图

编辑工作流时，优先使用本地源代码同步。将这些脚本用作调试、直接检查图或仅支持 API 的环境中的备用方案。

1. 获取图：node scripts/get-graph.js <workflow_id>（注意 lock_version）
2. 编辑 JSON（见下方的图规则）
3. 验证：node scripts/validate-graph.js --definition-file <path>
4. 更新：node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>
5. 重新获取以确认

对于小规模编辑，也可以改用 edit-graph.js，并指定 --old-file 和 --new-file。

如果遇到 lock_version 冲突：重新获取图、重新应用更改，并使用新的 lock_version 重试。

管理触发器

1. 列出：node scripts/list-triggers.js <workflow_id>
2. 创建：node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>
3. 切换状态：node scripts/update-trigger.js --trigger-id <id> --active true|false
4. 删除：node scripts/delete-trigger.js --trigger-id <id>

对于 inbound_message 触发器，优先使用 kapso whatsapp numbers resolve --phone-number "<display-number>" --output json 获取准确的 phone_number_id。如果 CLI 不可用，则使用 node scripts/list-whatsapp-phone-numbers.js 作为备用方案。

对于 project_event 触发器，如果用户正在定义事件类型或架构，请先注册或更新 Project Event 定义：

node scripts/project-event-definitions.js create \
  --name conversation.csat_scored \
  --description "Customer satisfaction score for a conversation" \
  --property-schema '{"score":{"type":"number"},"reason":{"type":"string"}}'

然后创建触发器：

node scripts/create-trigger.js <workflow_id> \
  --trigger-type project_event \
  --triggerable-attributes '{"event_name":"conversation.csat_scored","property_key":"score","operator":"gte","property_value":4}'

定义仅包含元数据。除非用户明确接受此副作用，否则不要仅为注册名称而发送示例事件。

管理 Project Event 定义

使用定义来设置事件名称、描述和平面标量属性架构。发送的事件是独立记录，可通过 POST /platform/v1/events、emit_event 节点、Function 节点的 project_events 或 Agent 节点的 emit_event 创建。

1. 列出：node scripts/project-event-definitions.js list
2. 按名称创建或更新：node scripts/project-event-definitions.js create --name <event.name> [--description <text>] [--property-schema <json>]
3. 按 ID 更新：node scripts/project-event-definitions.js update --definition-id <id> [--name <event.name>] [--description <text>] [--property-schema <json>]

使用 Project Events 构建工作流

当工作流需要记住或响应持久化的业务事实时，请使用此清单：

1. 如果用户要引入新的事件名称或架构，请先定义事件。
2. 当工作流需要响应已发出的事件时，使用 project_event 触发器。
3. 使用 emit_event 节点确定性地在工作流步骤中发出事件。
4. 如果是否发出事件取决于函数代码的输出，请在 Function 节点中使用 project_events。
5. 只有当 Agent 应决定是否以及何时记录事实时，才使用 Agent 节点的 emit_event。启用 emit_event 默认工具，并配置允许的事件定义后，再依赖此功能。

由 Project Event 触发的工作流是观察者，不能发出 Project Events。请勿在从 Project Event 触发器启动的工作流中添加事件发出操作。

调试执行

1. 如果有执行 ID，请先搜索工作流日志：kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --limit 20 --output json
2. 列出：node scripts/list-executions.js <workflow_id>
3. 检查：node scripts/get-execution.js <execution-id>
4. 获取值：node scripts/get-context-value.js <execution-id> --variable-path vars.foo
5. 事件：node scripts/list-execution-events.js <execution-id>

创建并部署函数

1. 按处理程序签名编写代码（见下方函数规则）
2. 创建：node scripts/create-function.js --name <name> --code-file <path> [--public-endpoint true]
3. 部署：node scripts/deploy-function.js --function-id <id>
4. 验证：node scripts/get-function.js --function-id <id>

当函数需要通过 Kapso 托管的调用 URL，在不使用 X-API-Key 的情况下被调用时，使用 --public-endpoint true。此功能仅适用于 Cloudflare 函数。 新函数默认使用 invoke_response_mode=passthrough，成功调用时会直接返回函数正文。之后可以使用 update-function.js 迁移旧版封装函数。

使用远程沙盒仓库设置 Agent 节点

当 Agent 需要远程临时工作区，以便在工作流运行期间检查或修改仓库文件时，请使用此配置。

1. 阅读 references/agent-remote-sandbox.md，了解执行模型和字段规则
2. 查找模型：node scripts/list-provider-models.js
3. 将 assets/agent-remote-sandbox-github-repo-example.json 复制为起始配置，或编辑 data.config 下的 Agent 节点
4. 设置 sandbox_enabled: true
5. 将 sandbox_network_mode 设为 allow_all 或 allow_list
6. 如果使用 allow_list，请在 sandbox_allowed_outbound_hosts 中添加其他出站主机
7. 将 GitHub 仓库添加到 flow_agent_resources，并包含：
   • resource_type: "github_repository"
   • repo_url
   • branch
   • pat
8. 编写系统提示词，明确要求在进行更改前读取 /workspace/repos/<repo-slug>
9. 验证并更新图

注意：

• 远程沙盒目前处于 Beta 阶段，Beta 期间免费
• sandbox_enabled 控制是否启用远程工作区和沙盒工具
• 即使之后关闭沙盒访问，仓库资源仍会保留配置
• v1 仅支持 GitHub 仓库
• 请使用仓库根 URL，不要使用 GitHub 文件 URL 或 tree/... URL
• 仓库会挂载到远程沙盒内的 /workspace/repos/<repo-slug>
• 具体格式请参阅 references/agent-remote-sandbox.md 和 references/node-types.md

图规则

• 必须且只能有一个 id = start 的开始节点
• 切勿更改现有节点 ID
• 新节点 ID 使用 {node_type}_{timestamp_ms} 格式
• 非 decide 节点的出站 next 边为 0 或 1 条
• Decide 边标签必须与 conditions[].label 匹配
• 边键为 source/target/label（而非 from/to）

完整架构详情请参阅 references/graph-contract.md。

函数规则

async function handler(request, env) {
  // Parse input
  const body = await request.json();
  // Use env.KV and secrets as needed
  return new Response(JSON.stringify({ result: "ok" }));
}

• 不要使用 export、export default 或箭头函数
• 返回 Response 对象

执行上下文

始终使用以下结构：

• vars - 用户定义的变量
• system - 系统变量
• context - 通道数据
• metadata - 请求元数据

脚本

工作流

脚本	用途
list-workflows.js	列出工作流（仅元数据）
get-workflow.js	获取工作流元数据
create-workflow.js	创建工作流
update-workflow-settings.js	更新工作流设置

图

脚本	用途
get-graph.js	获取工作流图和 lock_version
edit-graph.js	通过字符串替换修补图
update-graph.js	替换整个图
validate-graph.js	在本地验证图结构

触发器

脚本	用途
list-triggers.js	列出工作流的触发器
create-trigger.js	创建触发器
update-trigger.js	启用/禁用触发器
delete-trigger.js	删除触发器
list-whatsapp-phone-numbers.js	列出用于设置触发器的电话号码

项目事件

脚本	用途
project-event-definitions.js	列出、创建或更新项目事件定义

执行

脚本	用途
list-executions.js	列出执行
get-execution.js	获取执行详情
get-context-value.js	从执行上下文读取值
update-execution-status.js	强制设置执行状态
resume-execution.js	恢复等待中的执行
list-execution-events.js	列出执行事件

函数

脚本	用途
list-functions.js	列出项目函数
get-function.js	获取函数详情和代码
create-function.js	创建函数，可选择添加公共调用端点
update-function.js	更新函数代码、公共端点设置，或将旧版封装函数迁移为直通函数
deploy-function.js	将函数部署到运行时
invoke-function.js	使用负载调用函数
list-function-invocations.js	列出函数调用记录

OpenAPI

脚本	用途
openapi-explore.mjs	探索 OpenAPI（search/op/schema/where）

安装依赖（仅需一次）：

npm i

示例：

node scripts/openapi-explore.mjs --spec workflows search "variables"
node scripts/openapi-explore.mjs --spec workflows op getWorkflowVariables

注意事项

• 优先使用文件路径，而不是内联 JSON（--definition-file、--code-file）
• 调试工作流时，如果需要结合 API 调用、Meta 事件或 webhook 投递记录进行跨来源 Logs 搜索，请使用 observe-whatsapp。
• 变量的 CRUD 操作（variables-set.js、variables-delete.js）已被禁用，因为 Platform API 不支持此功能

参考资料

请阅读与你要更改的操作相关的参考资料：

• references/local-workflow-source.md - 本地工作流源代码编辑和 CLI 同步
• references/graph-contract.md - 图编辑：架构、计算字段与可编辑字段，以及 lock_version
• references/node-types.md - 添加或更改节点配置
• references/workflow-overview.md - 执行行为、状态更改和恢复

如果只处理函数，请阅读下方的函数参考资料；只有在工作流也发生更改时，才需要阅读图/源代码参考资料。其他特定任务的参考资料：

• references/execution-context.md - 上下文结构和变量替换
• references/triggers.md - 触发器类型和设置
• references/agent-remote-sandbox.md - 远程沙箱行为、仓库资源和挂载路径
• references/functions-reference.md - 函数管理
• references/functions-payloads.md - 函数的负载形状

资源

文件	描述
workflow-linear.json	最简线性工作流
workflow-decision.json	最简分支工作流
workflow-agent-simple.json	最简 Agent 工作流
workflow-customer-support-intake-agent.json	客户支持接待
workflow-interactive-buttons-decide-function.json	交互式按钮 + decide（函数）
workflow-interactive-buttons-decide-ai.json	交互式按钮 + decide（AI）
workflow-api-template-wait-agent.json	API 触发器 + 模板 + Agent
function-decide-route-interactive-buttons.json	用于按钮路由的函数
agent-remote-sandbox-github-repo-example.json	包含远程沙箱和 GitHub 仓库资源的 Agent 节点

相关技能

• integrate-whatsapp - 入门、Webhook、消息、模板、流程
• observe-whatsapp - 调试、日志、健康检查

[automate-whatsapp file map]|root: .
|.:{package.json,SKILL.md}
|assets:{agent-remote-sandbox-github-repo-example.json,function-decide-route-interactive-buttons.json,functions-example.json,workflow-agent-simple.json,workflow-api-template-wait-agent.json,workflow-customer-support-intake-agent.json,workflow-decision.json,workflow-interactive-buttons-decide-ai.json,workflow-interactive-buttons-decide-function.json,workflow-linear.json}
|references:{agent-remote-sandbox.md,execution-context.md,function-contracts.md,functions-payloads.md,functions-reference.md,graph-contract.md,local-workflow-source.md,node-types.md,triggers.md,workflow-overview.md,workflow-reference.md}
|scripts:{create-function.js,create-trigger.js,create-workflow.js,delete-trigger.js,deploy-function.js,edit-graph.js,get-context-value.js,get-execution-event.js,get-execution.js,get-function.js,get-graph.js,get-workflow.js,invoke-function.js,list-execution-events.js,list-executions.js,list-function-invocations.js,list-functions.js,list-provider-models.js,list-triggers.js,list-whatsapp-phone-numbers.js,list-workflows.js,openapi-explore.mjs,project-event-definitions.js,resume-execution.js,update-execution-status.js,update-function.js,update-graph.js,update-trigger.js,update-workflow-settings.js,validate-graph.js,variables-delete.js,variables-list.js,variables-set.js}
|scripts/lib/functions:{args.js,kapso-api.js}
|scripts/lib/workflows:{args.js,kapso-api.js,result.js}