automate-whatsapp

WhatsApp を自動化する

使用するタイミング

ワークフローの CRUD、グラフの編集、WhatsApp および Project Event のトリガー、Project Event の発行、実行、関数の管理、Webhook ツール、MCP ツールなど、WhatsApp の自動化を構築して実行する際にこのスキルを使用します。

セットアップ

推奨の方法：

• 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 トリガーでは、正確な phone_number_id を取得するため、kapso whatsapp numbers resolve --phone-number "<display-number>" --output json を優先してください。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 ノードの 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 で移行できます。

リモートサンドボックスリポジトリを使用したエージェントノードの設定

ワークフローの実行中にリポジトリファイルを検査または変更するため、エージェントにリモートの一時的なワークスペースが必要な場合に使用します。

1. 実行モデルとフィールドのルールについて、references/agent-remote-sandbox.md を読みます
2. モデルを検索します：node scripts/list-provider-models.js
3. assets/agent-remote-sandbox-github-repo-example.json を出発点としてコピーするか、data.config の下にあるエージェントノードを編集します
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. グラフを検証して更新します

注：

• リモートサンドボックスはベータ版で、ベータ期間中は無料です
• sandbox_enabled は、リモートワークスペースとサンドボックスツールを使用できるかどうかを制御します
• サンドボックスへのアクセスを後から無効にしても、リポジトリリソースの設定は維持されます
• v1 でサポートされるのは GitHub リポジトリのみです
• GitHub のファイル URL や tree/... URL ではなく、リポジトリのルート URL を使用します
• リポジトリはリモートサンドボックス内の /workspace/repos/<repo-slug> にマウントされます
• 正確な形式については、references/agent-remote-sandbox.md と references/node-types.md を参照してください

グラフのルール

• id が start の開始ノードを必ず 1 つだけ設定します
• 既存のノード 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 配信とあわせて複数ソースのログを検索するには、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	最小構成のエージェントワークフロー
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 リポジトリリソースを備えたエージェントノード

関連スキル

• integrate-whatsapp - オンボーディング、ウェブフック、メッセージング、テンプレート、フロー
• 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}