observe-whatsapp

WhatsApp を監視する

使用するタイミング

運用上の診断にこのスキルを使用します。ログ検索、メッセージ配信の調査、Webhook 配信のデバッグ、エラーのトリアージ、ワークフローイベントの関連付け、WhatsApp のヘルスチェックに役立ちます。

セットアップ

推奨方法：

• Kapso CLI をインストールして認証します（kapso login）
• kapso status を実行して、プロジェクトへのアクセス権と利用可能な WhatsApp 番号を確認します

代替方法： 環境変数：

• KAPSO_API_BASE_URL（ホストのみ。/platform/v1 は含めません）
• KAPSO_API_KEY

使用方法

ログを検索する

ユーザーから識別子、エンドポイント、メッセージ ID、ワークフロー実行 ID、Webhook 配信 ID、リクエスト ID が提示された場合や、「何が起きたのか？」という曖昧なデバッグ依頼があった場合は、まず Logs 検索を使用します。

推奨方法：

1. 現在のプロジェクトを検索します：kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json
2. 完全一致の検索結果がない場合は、ログがないと結論づける前に --period 7d を指定して再試行します。
3. 広範なエラースキャンには --problems-only を追加します。正確なタイムラインを再構築する場合は指定しません。
4. 検索範囲を意図的に絞り込む場合にのみ、明示的なフィルターを追加します：
   • ワークフロー実行：kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --output json
   • API エンドポイント／ステータス：kapso logs search --source external_api_log --filter endpoint_contains=/messages --filter response_status=500 --period 24h --output json
   • WhatsApp メッセージ ID：kapso logs search --query "wamid..." --source whatsapp_webhook_event --filter whatsapp_message_id=wamid... --period 7d --output json
   • Webhook 配信：kapso logs search --source webhook_delivery --filter webhook_id=<webhook-id> --period 24h --output json

代替方法：

1. Platform API 経由で検索します：node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20
2. 繰り返し指定するフラグを使ってフィルターを適用します：node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d
3. ソースとフィルターのオプションを確認します：node scripts/log-search.js --catalog true

Logs のソースは external_api_log、whatsapp_webhook_event、flow_event、webhook_delivery です。Platform API の代替方法では、API キーに紐づくプロジェクトのインデックス済み Logs ペイロードが返されます。この方法を使用するには、Logs と Elasticsearch が有効になっている必要があります。

メッセージ配信を調査する

推奨方法：

1. まず WAMID または顧客の電話番号を検索します：kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json
2. 番号を特定します：kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
3. 最近のメッセージを一覧表示します：kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json
4. 特定のメッセージを調べます：kapso whatsapp messages get <message-id> --phone-number-id <id> --output json
5. 会話を調べます：kapso whatsapp conversations list --phone-number "<display-number>" --output json

代替方法：

1. メッセージを一覧表示します：node scripts/messages.js --phone-number-id <id>
2. メッセージを調べます：node scripts/message-details.js --message-id <id>
3. 会話を検索します：node scripts/lookup-conversation.js --phone-number <e164>

エラーをトリアージする

推奨方法：

1. プロジェクトと番号の状態を確認します：kapso status
2. 番号のヘルスチェックを実行します：kapso whatsapp numbers health --phone-number "<display-number>" --output human
3. 最近の問題ログを検索します：kapso logs search --problems-only --period 24h --source all --limit 20 --output json
4. 必要に応じて、関連するテンプレートを調べます：kapso whatsapp templates list --phone-number "<display-number>" --output json

代替方法：

1. Logs を検索します：node scripts/log-search.js --problems-only true --period 24h --limit 20
2. メッセージのエラーを確認します：node scripts/errors.js
3. API ログを確認します：node scripts/api-logs.js
4. Webhook 配信を確認します：node scripts/webhook-deliveries.js

ヘルスチェックの実行

推奨する方法：

1. プロジェクトの概要：kapso status
2. 電話番号のヘルスチェック：kapso whatsapp numbers health --phone-number "<display-number>" --output human

代替方法：

1. プロジェクトの概要：node scripts/overview.js
2. 電話番号のヘルスチェック：node scripts/whatsapp-health.js --phone-number-id <id>

スクリプト

メッセージ

スクリプト	用途
messages.js	メッセージの一覧表示
message-details.js	メッセージの詳細を取得
lookup-conversation.js	電話番号または ID で会話を検索

エラーとログ

スクリプト	用途
log-search.js	API、Meta webhook、ワークフロー、webhook-delivery の各ソースにまたがってログを検索
errors.js	メッセージエラーの一覧表示
api-logs.js	外部 API ログの一覧表示
webhook-deliveries.js	webhook 配信の試行履歴を一覧表示

ヘルス

スクリプト	用途
overview.js	プロジェクトの概要
whatsapp-health.js	電話番号のヘルスチェック

OpenAPI

スクリプト	用途
openapi-explore.mjs	OpenAPI を探索（search/op/schema/where）

依存関係をインストールします（初回のみ）：

npm i

例：

node scripts/openapi-explore.mjs --spec platform search "webhook deliveries"
node scripts/openapi-explore.mjs --spec platform op listWebhookDeliveries
node scripts/openapi-explore.mjs --spec platform schema WebhookDelivery

注意事項

• webhook のセットアップ（作成／更新／削除、署名検証、イベントタイプ）には、integrate-whatsapp を使用してください。
• Project Event の定義、イベントをトリガーとするワークフローのセットアップ、または emit_event グラフの変更には、automate-whatsapp を使用してください。
• 詳細なデバッグを行う前に、表示用電話番号を正規の phone_number_id に解決することをおすすめします。
• メッセージ、ワークフロー、API 呼び出し、webhook 配信を横断して関連付ける場合は、従来の単一リソースのログエンドポイントより先に Logs 検索を使用してください。
• CLI を利用できない場合や、API ログまたは webhook 配信の調査が必要な場合に備えて、スクリプトを代替手段として残してください。

参考資料

• references/message-debugging-reference.md - メッセージのデバッグガイド
• references/triage-reference.md - エラーのトリアージガイド
• references/health-reference.md - ヘルスチェックガイド

関連スキル

• integrate-whatsapp - オンボーディング、webhook、メッセージング、テンプレート、フロー
• automate-whatsapp - ワークフロー、エージェント、自動化

[observe-whatsapp file map]|root: .
|.:{package.json,SKILL.md}
|assets:{health-example.json,message-debugging-example.json,triage-example.json}
|references:{health-reference.md,message-debugging-reference.md,triage-reference.md}
|scripts:{api-logs.js,errors.js,log-search.js,lookup-conversation.js,message-details.js,messages.js,openapi-explore.mjs,overview.js,webhook-deliveries.js,whatsapp-health.js}
|scripts/lib/messages:{args.js,kapso-api.js}
|scripts/lib/status:{args.js,kapso-api.js}
|scripts/lib/triage:{args.js,kapso-api.js}