automate-whatsapp

自動化 WhatsApp

使用時機

使用此技能來建置與執行 WhatsApp 自動化：工作流程 CRUD、圖形編輯、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 推送所有本機函式與工作流程。參閱 references/local-workflow-source.md 了解儲存庫結構、來源檔案行為與僅 JSON 編輯。

先探索電話號碼

建議路徑：

檢查專案狀態：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 觸發器，當使用者定義事件類型/結構時，先註冊或更新 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 建立的獨立記錄。

列出：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 Events 建置工作流程

當工作流程需要記住或回應持久性業務事實時，使用此檢查清單：

當使用者引入新事件名稱或結構時，先定義事件。
當工作流程應回應已發送事件時，使用 project_event 觸發器。
使用 emit_event 節點進行確定性的工作流程步驟發送。
當發送取決於函式程式碼輸出時，使用 Function 節點 project_events。
僅當代理應決定是否/何時記錄事實時，使用 Agent 節點 emit_event。依賴它之前，啟用 emit_event 預設工具並設定允許的事件定義。

由 Project Event 觸發的工作流程是觀察者，不能發送 Project Events。不要將事件發送新增到以 Project 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 託管的 invoke URL 在沒有 X-API-Key 的情況下呼叫時，使用 --public-endpoint true。這僅支援 Cloudflare 函式。
新函式預設為 invoke_response_mode=passthrough，成功 invoke 時直接回傳函式主體。舊版包裝函式之後可使用 update-function.js 遷移。

設定具有遠端沙箱儲存庫的 Agent 節點

當代理需要在工作流程執行期間檢查或修改儲存庫檔案時，使用此功能。

閱讀 references/agent-remote-sandbox.md 了解執行模型與欄位規則
尋找模型：node scripts/list-provider-models.js
複製 assets/agent-remote-sandbox-github-repo-example.json 作為起點，或編輯 data.config 下的 agent 節點
設定 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>
驗證並更新圖形

注意事項：

遠端沙箱為 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 節點有 0 或 1 個對外 next 邊
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 Events

指令碼	用途
`project-event-definitions.js`	列出、建立或更新 Project Event 定義

執行

指令碼	用途
`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`	建立函式，可選擇公開 invoke 端點
`update-function.js`	更新函式程式碼、公開端點設定，或將舊版包裝函式遷移至 passthrough
`deploy-function.js`	部署函式至執行環境
`invoke-function.js`	使用 payload 呼叫函式
`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）已封鎖 - Platform 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 - 函式的 payload 結構

資產

檔案	描述
`workflow-linear.json`	最小線性工作流程
`workflow-decision.json`	最小分支工作流程
`workflow-agent-simple.json`	最小代理工作流程
`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 觸發器 + 範本 + 代理
`function-decide-route-interactive-buttons.json`	按鈕路由函式
`agent-remote-sandbox-github-repo-example.json`	具有遠端沙箱 + GitHub 儲存庫資源的 Agent 節點

您可能也喜歡

debugging-and-error-recovery

77Kbackend-api

引導系統性的根本原因除錯。當測試失敗、建置中斷、行為不如預期，或遇到任何非預期錯誤時使用。當你需要系統性的方法來找出並修復根本原因，而非胡亂猜測時使用。

addyosmani

獲取

api-patterns

46Kbackend-api

API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.

sickn33

獲取

zustand

81Kbackend-api

LobeHub 的 Zustand store 開發規範。適用於修改 src/store、store slice、公開/內部 action、dispatch action、flattenActions、樂觀更新（optimistic updates）、selector、map 或類別化 action（class action）遷移等情境。

lobehub

獲取

繼續探索

瀏覽 backend-api 熱門 Skills 最近更新