automate-whatsapp

自动化 WhatsApp

使用时机

使用此技能来构建和运行 WhatsApp 自动化：工作流 CRUD、图编辑、WhatsApp 和项目事件触发器、项目事件发射、执行、函数管理、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。

首先发现电话号码

首选路径：

检查项目状态：kapso status
列出已连接号码：kapso whatsapp numbers list --output json
需要时解析显示号码：kapso whatsapp numbers resolve --phone-number "<display-number>" --output json

备用路径：

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

通过 API 脚本编辑工作流图

对于工作流编辑，优先使用本地源同步。这些脚本作为调试、直接图检查或仅 API 环境的备用方案。

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

对于小编辑，改用 edit-graph.js 并使用 --old-file 和 --new-file。

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

管理触发器

列出：node scripts/list-triggers.js <workflow_id>
创建：node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>
切换：node scripts/update-trigger.js --trigger-id <id> --active true|false
删除：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 触发器，当用户定义事件类型/模式时，首先注册或更新项目事件定义：

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}'

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

管理项目事件定义

使用定义来管理事件名称、描述和平面标量属性模式。发出的事件是由 POST /platform/v1/events、emit_event 节点、函数节点 project_events 或代理节点 emit_event 创建的单独记录。

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

使用项目事件构建工作流

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

当用户引入新事件名称或模式时，首先定义事件。
当工作流应响应发出的事件时，使用 project_event 触发器。
对于确定性的工作流步骤发射，使用 emit_event 节点。
当发射取决于函数代码输出时，使用函数节点 project_events。
仅当代理应决定是否/何时记录事实时，使用代理节点 emit_event。在依赖它之前，启用 emit_event 默认工具并配置允许的事件定义。

项目事件触发的工作流是观察者，不能发出项目事件。不要向从项目事件触发器启动的工作流添加事件发射。

调试执行

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

创建和部署函数

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

当函数应通过 Kapso 托管的调用 URL 无需 X-API-Key 即可调用时，使用 --public-endpoint true。这仅适用于 Cloudflare 函数。
新函数默认使用 invoke_response_mode=passthrough，成功调用时直接返回函数体。旧版包装函数可以稍后使用 update-function.js 迁移。

设置带有远程沙箱仓库的代理节点

当代理需要在工作流运行期间检查或修改仓库文件的远程临时工作区时使用。

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

注意：

远程沙箱是测试版，测试期间免费
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}
非决策节点有 0 或 1 条出站 next 边
决策边标签必须与 conditions[].label 匹配
边键是 source/target/label（不是 from/to）

有关完整模式详细信息，请参阅 references/graph-contract.md。

函数规则

async function handler(request, env) {
  // 解析输入
  const body = await request.json();
  // 根据需要使用 env.KV 和 secrets
  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`	更新函数代码、公共端点设置，或将旧版包装函数迁移到 passthrough
`deploy-function.js`	将函数部署到运行时
`invoke-function.js`	使用负载调用函数
`list-function-invocations.js`	列出函数调用

OpenAPI

脚本	用途
`openapi-explore.mjs`	探索 OpenAPI（搜索/操作/模式/位置）

安装依赖（一次）：

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 投递时，使用 observe-whatsapp 进行跨源日志搜索。
变量 CRUD（variables-set.js、variables-delete.js）被阻止 - 平台 API 不支持

参考

编辑前阅读：

references/local-workflow-source.md - CLI 源同步、仓库布局和 @kapso/workflows
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`	最小代理工作流
`workflow-customer-support-intake-agent.json`	客户支持受理
`workflow-interactive-buttons-decide-function.json`	交互式按钮 + 决策（函数）
`workflow-interactive-buttons-decide-ai.json`	交互式按钮 + 决策（AI）
`workflow-api-template-wait-agent.json`	API 触发器 + 模板 + 代理
`function-decide-route-interactive-buttons.json`	用于按钮路由的函数
`agent-remote-sandbox-github-repo-example.json`	带有远程沙箱 + GitHub 仓库资源的代理节点

你可能还喜欢

debugging-and-error-recovery

77Kbackend-api

指导系统性的根因调试。当测试失败、构建中断、行为不符合预期或遇到任何意外错误时使用。当你需要系统性地查找并修复根本原因而非猜测时使用。

addyosmani

获取

zustand

81Kbackend-api

LobeHub Zustand 存储约定。在编辑 src/store、存储切片、公共/内部动作、调度动作、flattenActions、乐观更新、选择器、映射或类动作迁移时使用。

lobehub

获取

telegram-bot-builder

44Kbackend-api

构建解决实际问题的Telegram机器人的专家——从简单自动化到复杂的AI驱动机器人。涵盖机器人架构、Telegram Bot API、用户体验、变现策略以及将机器人扩展到数千用户。

sickn33

获取

继续探索

上一个相关 Skillanysearch 下一个相关 Skillxurl

浏览 backend-api 热门 Skills 最近更新