kapso-ops

Kapso Ops

适用场景

在进行运维诊断时使用此技能：配置 webhook、调查消息送达情况、排查错误，以及检查 WhatsApp 健康状况。

设置

环境变量：

• KAPSO_API_BASE_URL（仅主机地址，不含 /platform/v1）
• KAPSO_API_KEY

使用方法

配置 webhook

1. 创建：node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>
2. 验证签名处理方式（参见 references/webhooks-overview.md）
3. 测试：node scripts/test.js --webhook-id <id>

调查消息送达情况

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. 消息错误：node scripts/errors.js
2. API 日志：node scripts/api-logs.js
3. Webhook 投递记录：node scripts/webhook-deliveries.js

运行健康检查

1. 项目概览：node scripts/overview.js
2. 电话号码健康状况：node scripts/whatsapp-health.js --phone-number-id <id>

脚本

Webhook

脚本	用途
list.js	列出某个电话号码的 webhook
get.js	获取 webhook 详情
create.js	创建 webhook
update.js	更新 webhook
delete.js	删除 webhook
test.js	向 webhook 发送测试事件

创建/更新时的常用标志：

• --url <https://...> - Webhook URL
• --events <csv> - 事件类型（以逗号分隔）
• --kind <kapso|meta> - Webhook 类型
• --payload-version <v1|v2> - 负载格式（推荐使用 v2）
• --buffer-enabled <true|false> - 启用缓冲
• --active <true|false> - 启用/禁用

消息

脚本	用途
messages.js	列出消息
message-details.js	获取消息详情
lookup-conversation.js	按电话号码或 ID 查找对话

错误和日志

脚本	用途
errors.js	列出消息错误
api-logs.js	列出外部 API 日志
webhook-deliveries.js	列出 webhook 投递尝试记录

健康检查

脚本	用途
overview.js	项目概览
whatsapp-health.js	电话号码健康检查

备注

• 对于 whatsapp.message.* 事件，请使用配置级 webhook
• 新集成推荐使用负载版本 v2
• Meta webhook 提供原始负载；Kapso webhook 支持缓冲

参考资料

• references/webhooks-reference.md - Webhook API 参考
• references/webhooks-overview.md - Webhook 概念和设置
• references/webhooks-event-types.md - 可用事件类型
• references/message-debugging-reference.md - 消息调试指南
• references/triage-reference.md - 错误排查指南
• references/health-reference.md - 健康检查指南

相关技能

• kapso-automation - 自动化和函数
• whatsapp-messaging - WhatsApp 消息
• kapso-api - 平台 API 和客户