observe-whatsapp

observe-whatsapp スキルの概要

observe-whatsapp スキルは、Kapso における WhatsApp の運用状況を診断するためのものです。メッセージ配信、webhook のリトライ、API エラー、番号の健全性を確認できます。サポートエンジニア、運用担当者、インテグレーターが、「何かが失敗した」状態から素早く具体的な原因へたどり着くために作られており、最初からすべての repo ファイルを読む必要はありません。

observe-whatsapp スキルは、メッセージが送信済みか、配信済みか、既読かを確認したいとき、webhook が届かなかった理由を特定したいとき、WhatsApp の設定が劣化・ブロック・正常のどれに当たるかを判断したいときに使います。価値の中心は単なる診断ではなく、より明確な切り分けの道筋にあります。何を最初に確認すべきか、どの証拠が最も重要かを示してくれます。

observe-whatsapp が最も得意なこと

observe-whatsapp は、本番障害の切り分けに特に強いスキルです。とくに、メッセージ ID、電話番号、webhook の失敗、ヘルスチェックの失敗など、手がかりが1つでもある場合に向いています。一般的な WhatsApp の説明よりも、Kapso における運用状態の確認に重点があります。

observe-whatsapp の違い

このスキルは、ワークフロー主導で証拠ベースです。Kapso CLI の直接パスに加えてフォールバック用スクリプトも含まれているため、ログイン済みの CLI セッションでも、API 認証情報だけの環境でも使えます。observe-whatsapp for Observability は、症状だけを説明するプロンプトよりも実務に直結します。

どんなときに適しているか

配信タイムライン、webhook の試行、ヘルスシグナル、API ログを確認したいなら observe-whatsapp を選んでください。定型回答や一度きりの説明だけで足りるなら通常のプロンプトでも十分ですが、再現性のある診断が必要ならこのスキルのほうが適しています。

observe-whatsapp スキルの使い方

インストール時のコンテキストと前提条件

想定されているインストール手順は次のとおりです。

npx skills add gokapso/agent-skills --skill observe-whatsapp

最も良い結果を得るには、まず Kapso CLI を使ってください。kapso login で認証し、続けて kapso status を実行して、プロジェクトへのアクセス権と利用可能な WhatsApp 番号を確認します。CLI にアクセスできない場合でも、このスキルは KAPSO_API_BASE_URL と KAPSO_API_KEY を使う API ベースのフォールバックに対応しています。

あいまいな問題を使えるプロンプトに変える

このスキルは、実行可能な最小限の事実が入ったプロンプトで最もよく動きます。たとえば、電話番号、メッセージ ID、webhook イベント、タイムスタンプの範囲、正確なエラーテキストなどです。「WhatsApp が壊れている」ではなく、たとえば次のように書きます。「observe-whatsapp を使って、wamid.HBgMMTIzNDU2Nzg5 が delivered で止まった理由と、10:00 UTC 以降の webhook リトライが失敗したかを確認してください。」

もっとも早く答えにたどり着きやすい進め方

まずユーザーが見ている症状から始め、次に4つの経路のどれかに絞ります。メッセージ配信、webhook 配信、エラーの切り分け、ヘルスチェックです。実際には、このスキルは先に設定を確認し、その後で対象のアーティファクトを調べる流れを前提にしています。この順番にすることで、誤った手がかりを追うリスクを減らし、別の電話番号や会話を取り違えるのを防げます。

まず読むべきファイル

インストール時の理解を深めるには、まず SKILL.md を読み、次に references/health-reference.md、references/message-debugging-reference.md、references/triage-reference.md を確認してください。例が必要なら assets/health-example.json、assets/message-debugging-example.json、assets/triage-example.json を見てください。フォールバック用ツールを理解したい場合は、scripts/messages.js、scripts/message-details.js、scripts/webhook-deliveries.js、scripts/whatsapp-health.js を確認してください。

observe-whatsapp スキル FAQ

observe-whatsapp を使うのに Kapso CLI は必要ですか？

いいえ。ただし、推奨ルートではあります。このスキルは kapso status と WhatsApp のサブコマンドを使う前提で最もよく機能するように設計されています。CLI が使えない場合は、スクリプトと API 環境変数がフォールバックになります。

observe-whatsapp にはどんな入力が必要ですか？

症状だけでなく、識別子を渡してください。メッセージ ID、表示番号または E.164 形式の電話番号、phone-number ID、タイムスタンプ範囲、webhook イベント名、あるいは生のエラーメッセージです。入力が具体的であるほど、スキル側の推測は少なくて済みます。

observe-whatsapp は初心者向きですか？

はい。ただし、問題のおおまかな形が分かっていることが前提です。最初に何を確認すべきかを示してくれるので、空のプロンプトより使いやすいですが、少なくとも1つは具体的な WhatsApp のアーティファクトを渡せることを想定しています。

どんなときにこのスキルを使うべきではありませんか？

WhatsApp 以外の observability タスクや、製品レベルの戦略に関する質問には observe-whatsapp を使わないでください。また、ID もタイムスタンプもなく、ログやステータスシグナルにもアクセスできない場合も、このスキルには向きません。

observe-whatsapp スキルを改善するには

失敗した正確な地点を伝える

出力品質を最も早く高める方法は、ワークフローがどこで壊れたかを明示することです。たとえば、「送信されたが配信されない」「webhook は受信されたが Connection refused になった」「ヘルスが劣化していて webhook の検証に失敗した」といった書き方です。こうすると observe-whatsapp は広い説明を飛ばして、失敗したチェックに集中できます。

スキルが検証できる証拠を含める

強い入力には、メッセージ ID、使用した電話番号、時間帯、レスポンスの payload やエラーコードが含まれます。たとえば、「observe-whatsapp を使って、whatsapp.message.received の webhook 配信を 10:00 から 10:15 UTC の間で確認してください。最後の試行は 502 を返しました」という形は、「webhooks are down」よりはるかに有効です。

参照ファイルで初回出力を絞り込む

最初の回答が広すぎる場合は、references/health-reference.md の解釈ルールと references/triage-reference.md の切り分けロジックを見比べてください。これらの参照には、何を critical、degraded、retryable と扱うべきかが示されており、診断内容だけでなくユーザーに返す表現も改善できます。

変更は1つずつ加えて繰り返す

初回結果が不十分なら、新しい事実を1つだけ加えてプロンプトを絞り込みます。別の ID、より狭いタイムスタンプ範囲、あるいは失敗しているチェックの正確な名称です。observe-whatsapp では、問題全体を繰り返し説明するより、このやり方のほうがうまくいくことが多いです。スキルは、単一の運用経路をたどって根本原因に到達するよう作られているからです。