whatsapp-flows

WhatsApp フロー管理

使用する場面

WhatsApp フローを最初から最後まで管理する場合に、このスキルを使用します。フローの確認、バージョンを使ったフロー JSON の編集、公開とテスト、データエンドポイントの接続、応答やログの確認を行えます。

セットアップ

環境変数：

• KAPSO_API_BASE_URL（ホストのみ。/platform/v1 は含めません）
• KAPSO_API_KEY
• META_GRAPH_VERSION（任意。デフォルトは v24.0）

Node または Bun でスクリプトを実行します：

node scripts/list-flows.js

使用方法

フローの作成と公開

1. フローを作成します：node scripts/create-flow.js --phone-number-id <id> --name <name>
2. Flow JSON のルールについては、references/whatsapp-flows-spec.md を確認します
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>

データエンドポイントの接続（動的フロー）

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>

フローのデバッグ

• 応答の一覧表示：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 のルール

静的フロー（データエンドポイントなし）：

• version: "7.3" を使用します
• routing_model と data_api_version は任意です
• assets/sample-flow.json を参照してください

動的フロー（データエンドポイントあり）：

• data_api_version: "3.0" を指定して version: "7.3" を使用します
• 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 は使用しないでください
• 完了時には extension_message_response.params を指定した screen: "SUCCESS" を使用します
• endpoint_uri または data_channel_uri は含めないでください（Kapso が挿入します）

スクリプト

Platform API

スクリプト	目的
list-flows.js	すべてのフローを一覧表示
create-flow.js	新しいフローを作成
get-flow.js	フローの詳細を取得
read-flow-json.js	フロー JSON を読み取る
update-flow-json.js	フロー JSON を更新（新しいバージョンを作成）
publish-flow.js	フローを公開
get-data-endpoint.js	データエンドポイントの設定を取得
set-data-endpoint.js	データエンドポイントのコードを作成／更新
deploy-data-endpoint.js	データエンドポイントをデプロイ
register-data-endpoint.js	Meta にデータエンドポイントを登録
get-encryption-status.js	暗号化ステータスを確認
setup-encryption.js	フローの暗号化を設定

Meta プロキシ

スクリプト	目的
send-test-flow.js	テスト用フローメッセージを送信
delete-flow.js	フローを削除

ログと応答

スクリプト	目的
list-flow-responses.js	保存済みのフロー応答を一覧表示
list-function-logs.js	関数ログを一覧表示
list-function-invocations.js	関数呼び出しを一覧表示

トラブルシューティング

• プレビューに「flow_token is missing」と表示される：フローは動的ですが、データエンドポイントがありません。エンドポイントを接続して、再読み込みしてください。
• 暗号化の設定でエラーが発生する：電話番号／WABA の Settings で暗号化を有効にしてください。
• OAuthException 139000（Integrity）：Meta セキュリティセンターで WABA を認証する必要があります。

参考資料

• references/whatsapp-flows-spec.md - Flow JSON の仕様（編集前に確認してください）
• assets/sample-flow.json - 静的フローの例（エンドポイントなし）
• assets/dynamic-flow.json - 動的フローの例（エンドポイントあり）

関連スキル

• whatsapp-messaging - WhatsApp メッセージングとテンプレート
• kapso-automation - ワークフローの自動化
• kapso-api - Platform API と顧客