observe-whatsapp

observe-whatsapp 技能概覽

observe-whatsapp 技能可協助你在 Kapso 中診斷 WhatsApp 操作：訊息送達、webhook 重試、API 錯誤，以及號碼健康狀態。它是為支援工程師、營運人員與整合開發者設計的，目標是讓你能快速從「出問題了」縮小到具體原因，而不必先把整個 repo 每個檔案都讀過一遍。

當你需要確認訊息是否已送出、已送達或已讀；判斷 webhook 為什麼沒收到；或確認某個 WhatsApp 設定是否劣化、被阻擋，或仍然正常時，就適合使用 observe-whatsapp 技能。它的核心價值不只是排錯，而是提供更清楚的分流路徑：先看什麼、哪些證據最重要，會講得很明確。

observe-whatsapp 最適合處理的情境

observe-whatsapp 特別擅長生產環境排查，尤其是使用者手上已有 message ID、電話號碼、webhook 失敗資訊，或健康檢查失敗結果時。它關心的不是一般性的 WhatsApp 教學，而是 Kapso 裡的實際運作狀態。

observe-whatsapp 的差異在哪裡

這個技能是以工作流程為導向、以證據為基礎設計的。它同時提供直接的 Kapso CLI 路徑與備援腳本，所以不論你是在已登入的 CLI 工作階段，還是只能透過 API 憑證操作，都能使用。這也讓 observe-whatsapp for Observability 比只描述症狀的提示詞更實用。

什麼情況下適合使用

如果你需要檢查送達時間軸、webhook 嘗試紀錄、健康訊號或 API log，就選 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 備援方式。

把粗略問題改寫成可用提示詞

這個技能最適合的輸入，是最少但可行動的事實：電話號碼、message ID、webhook event、時間範圍，或精確的錯誤文字。舉例來說，不要只寫「WhatsApp 壞掉了」，而是改成：「Use observe-whatsapp to check why wamid.HBgMMTIzNDU2Nzg5 stopped at delivered and whether webhook retries failed after 10:00 UTC.」

通常最快得到答案的工作流程

先從使用者可感知的症狀出發，再縮小到四條路徑之一：訊息送達、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 需要提供哪些輸入？

請提供識別資訊，不要只丟症狀：message ID、顯示用號碼或 E.164 格式電話號碼、phone-number ID、時間區間、webhook event 名稱，或原始錯誤訊息。你的輸入越具體，技能需要自行推斷的部分就越少。

observe-whatsapp 適合新手嗎？

如果你已經大致知道問題長什麼樣子，答案是適合。它比空白提示詞更容易上手，因為它會告訴你先看什麼，但前提仍是你至少能提供一個具體的 WhatsApp 工件。

什麼情況下不該用這個技能？

不要把 observe-whatsapp 用在非 WhatsApp 的可觀測性工作上，也不要用來問產品層級的策略問題。當你沒有任何 ID、沒有時間戳，也拿不到 log 或狀態訊號時，這個技能也不適合。

如何改進 observe-whatsapp 技能

明確指出失敗發生在哪一步

要提升輸出品質，最快的方法就是直接說出工作流程卡在哪裡：例如「已送出但未送達」、「webhook 收到 Connection refused」、或「health 已劣化且 webhook 驗證失敗」。這能讓 observe-whatsapp 跳過大範圍說明，直接聚焦失敗的檢查點。

提供技能能驗證的證據

強而有力的輸入包含 message ID、使用的電話號碼、時間範圍，以及任何回應 payload 或錯誤碼。例如：「Use observe-whatsapp to inspect webhook deliveries for whatsapp.message.received between 10:00 and 10:15 UTC; last attempt returned 502」就遠比「webhooks 掛了」更有用。

善用參考檔案，讓第一次輸出更精準

如果第一輪回覆太過籠統，請對照 references/health-reference.md 裡的判讀規則，以及 references/triage-reference.md 裡的排錯邏輯。這些參考檔案會說明哪些狀態應視為 critical、degraded 或 retryable，能同時改善診斷結果與你回給使用者的措辭。

一次只改一個變因，逐步迭代

如果初次結果不完整，就只補上一個新事實：換一個 ID、縮小時間範圍，或補上確切失敗檢查項。對 observe-whatsapp 而言，這通常比把整個問題重講一次更有效，因為這個技能本來就是設計來沿著單一營運路徑追到根因。