integrate-whatsapp

integrate-whatsapp 技能概览

integrate-whatsapp 的作用

integrate-whatsapp 技能帮助你通过 Kapso 把 WhatsApp 接到产品里，覆盖从客户入驻到消息投递的完整流程。它最适合需要一份 integrate-whatsapp 指南、并且希望把安装链接、连接检测、webhook、模板发送、媒体和 WhatsApp Flows 放进同一条工作流里处理的场景。

最适合的使用场景

当你的后端系统需要满足以下需求时，建议使用这个 integrate-whatsapp skill：

• 将客户引导到他们自己的 WhatsApp Business 账号中完成入驻
• 检测某个号码何时已成功连接
• 通过 webhook 接收消息和会话事件
• 发送外发消息、模板和媒体
• 管理 Flows 的端点、加密和发布步骤

为什么值得安装这个技能

它的核心优势在于工作流足够完整。仓库同时提供了偏 CLI 的集成路径和偏 API 的集成路径，这一点在你的环境还在变化、或者需要支持多租户时尤其重要。如果你正在评估是否要做一次 integrate-whatsapp install，这个技能比通用提示词更强，因为它包含了真正会卡住生产落地的那些环节：ID、webhook 路由、setup-link 生命周期，以及项目级操作和手机号级操作之间的区别。

如何使用 integrate-whatsapp 技能

安装并确认上下文

使用 npx skills add gokapso/agent-skills --skill integrate-whatsapp 安装。 在请求实现帮助之前，先确认你的项目里已经有正确的仓库上下文，并先阅读 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 的消息发送路径。

优先阅读的文件和工作流

先从会直接影响实现选择的文件开始：

• references/getting-started.md：端到端流程
• references/detecting-whatsapp-connection.md：连接事件和跳转处理
• 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 能收到，但 signature verification 失败”
• “模板在测试环境能发，在生产环境不能发”
• “我拿错了 phone_number_id”

这类输入比泛泛地要一份集成方案，更能产出有用的 integrate-whatsapp usage 指导。

用合适的素材来迭代

如果第一次输出不完整，可以带着下面这些材料继续迭代：

• 你收到的 webhook payload
• 你想发送的 template JSON
• 你想发布的 Flow JSON
• kapso status、kapso whatsapp numbers list 的命令输出，或者你的 API response

在做 integrate-whatsapp guide 相关工作时，这些素材比宽泛的需求描述更重要，因为它们能让你更快修正 ID、事件名、跳转处理和 payload 结构。

注意生产环境里最常见的错误

最常见的失败模式是用了错误的 identifier、订阅了错误的 webhook 类型，或者默认 setup 完成就等于可以发消息。要提升技能输出质量，请明确说明你需要的是 project webhooks 还是 phone-number webhooks，你用的是 Kapso 还是 Meta proxy endpoints，以及你的应用是否必须支持 coexistence 还是 dedicated mode。