integrate-whatsapp

integrate-whatsapp 技能概覽

integrate-whatsapp 的用途

integrate-whatsapp 技能可協助你用 Kapso 把 WhatsApp 串接到產品中，從客戶導入到訊息送達都涵蓋在內。當你需要一份 integrate-whatsapp 指南，而且希望它把設定連結、連線偵測、webhook、模板發送、媒體與 WhatsApp Flows 放在同一條工作流程裡時，這個技能最實用。

最適合的使用情境

如果你的後端系統需要以下功能，建議使用這個 integrate-whatsapp skill：

• 將客戶導入到他們自己的 WhatsApp Business 帳戶
• 偵測某個號碼何時完成連線
• 透過 webhook 接收訊息與對話事件
• 發送對外訊息、模板與媒體
• 管理 Flows 的 endpoint、加密與發布步驟

這個技能值得安裝的原因

最大優勢在於流程完整。這個 repository 同時提供 CLI 優先與 API 優先兩條實作路徑，對於你的環境仍在變動、或需要支援多租戶時特別重要。如果你正在評估是否要做 integrate-whatsapp install，這個技能比一般提示詞更強，因為它納入了最常卡住正式上線的關鍵環節：ID、webhook 路由、setup-link 的生命週期，以及 project 層級與 phone-number 層級操作的差異。

如何使用 integrate-whatsapp 技能

安裝並確認內容脈絡

使用 npx skills add gokapso/agent-skills --skill integrate-whatsapp 來安裝。開始請求實作協助前，先確認你的專案中的 repository 內容脈絡，並先閱讀 SKILL.md。接著檢查 references/getting-started.md、references/platform-api-reference.md、references/webhooks-overview.md 與 references/setup-links.md，因為它們比快速掃過 assets 更能說明實際的整合路徑。

把模糊目標轉成可用提示詞

要得到更好的 integrate-whatsapp usage 結果，請描述：

• 你是用 Kapso CLI，還是直接呼叫 API
• 你的應用是多租戶還是單號碼
• 你卡在哪個步驟：導入、連線偵測、webhook 處理、發送，或 Flows
• 你手上已有的具體物件，例如 customer_id、phone_number_id、business_account_id 或 webhook secret

一個好的提示詞範例如下：

為多租戶 SaaS 實作 WhatsApp 導入流程。我已經有 customer_id，需要一個 setup-link 流程、whatsapp.phone_number.created 的 webhook 確認，以及使用 phone_number_id 的 send-message 路徑。

先閱讀的檔案與工作流程

先從會影響實作選擇的檔案開始：

• references/getting-started.md：端到端流程
• references/detecting-whatsapp-connection.md：連線事件與 redirect 處理
• references/webhooks-reference.md 與 references/webhooks-overview.md：事件送達規則與簽章驗證
• references/templates-reference.md：如果你要送模板或媒體
• references/whatsapp-flows-spec.md 加上 assets/sample-flow.json：如果你需要 Flows

建議提早查看的實用 assets：

• assets/webhooks-example.json
• assets/dynamic-flow.json
• assets/send-template-order-status-update.json
• assets/send-interactive-buttons.json

實務使用提示

當你在摸索專案狀態、客戶或號碼時，優先用 CLI；當你要把整合嵌進自己的後端時，則使用原始 API 呼叫。不要把 setup-link 導入和訊息發送混為一談：導入處理的是建立或解析已連線的號碼，而發送則需要正確的 phone_number_id。這個差異是成功使用 integrate-whatsapp usage 的核心，也能避開大多數整合錯誤。

integrate-whatsapp 技能常見問題

這只適合後端開發嗎？

是的，這個 integrate-whatsapp for Backend Development 技能主要就是給後端工作使用。它適合伺服器端導入、webhook 處理、API 驗證與訊息協調；它不是 UI 文案技能，也不是純粹用來寫行銷內容的提示詞範本。

這和一般提示詞有什麼不同？

一般提示詞往往只會很籠統地描述 WhatsApp 整合。integrate-whatsapp skill 更有用，因為它反映的是實際的整合面：setup-link、webhook 事件、號碼解析，以及 WhatsApp Flows。當你需要的是可部署的內容，而不是僅供說明的範例時，這種差異就能大幅減少摸索成本。

我一定要用 Kapso CLI 嗎？

不一定，但這個技能裡預設偏向 CLI，因為它有助於專案選擇、設定與號碼探索。如果你的團隊無法使用 CLI 工具，這些參考文件仍然支援透過 X-API-Key 直接呼叫 API。

什麼情況下不該用 integrate-whatsapp？

如果你只想看 WhatsApp 產品層級的高階概覽，或你要串接的是完全不同的供應商、也不打算使用 Kapso 的平台 API，就先不要用這個技能。如果你只需要一個一次性的訊息範例，沒有導入或 webhook 需求，這個技能也不太適合。

如何改進 integrate-whatsapp 技能

提供正確的起始狀態

最好的改進方式，是提供真實的整合狀態：目前的 project ID、客戶是否已存在、你擁有的 webhook endpoint，以及你要發送的訊息類型。這會讓 integrate-whatsapp install 的結果更可執行，因為技能能直接判斷你的流程從哪裡開始，而不是從零重講一次設定。

明確說出失敗模式

如果你想要更好的結果，請直接指出阻礙：

• “setup link 有打開，但沒有建立 phone number”
• “webhook 有收到，但簽章驗證失敗”
• “template 在測試環境可發送，但正式環境不行”
• “我拿到的是錯的 phone_number_id”

這類輸入比泛泛要求一份整合計畫，更能產生有用的 integrate-whatsapp usage 指引。

用對素材來反覆調整

如果第一次輸出不完整，可以改用以下其中一種素材繼續迭代：

• 你收到的 webhook payload
• 你想發送的 template JSON
• 你想發布的 Flow JSON
• kapso status、kapso whatsapp numbers list 的命令輸出，或你的 API 回應

對 integrate-whatsapp guide 這類工作來說，這些素材比寬泛需求更重要，因為它們能讓你快速修正 ID、事件名稱、redirect 處理與 payload 結構。

留意常見的正式環境錯誤

最常見的失敗模式，是用了錯的 identifier、訂閱了錯的 webhook 類型，或誤以為 setup 完成就代表已經可以發訊息。要提升這個技能的輸出品質，請清楚說明你需要的是 project webhooks 還是 phone-number webhooks、你是使用 Kapso 還是 Meta proxy endpoints，以及你的應用必須支援 coexistence 還是 dedicated mode。