observe-whatsapp

观察 WhatsApp

使用场景

在进行运维诊断时使用此技能：搜索日志、调查消息送达情况、调试 Webhook 送达情况、错误分类、工作流事件关联，以及检查 WhatsApp 健康状态。

设置

首选方式：

• 已安装并完成身份验证的 Kapso CLI（kapso login）
• 运行 kapso status，确认项目访问权限和可用的 WhatsApp 号码

备用方式： 环境变量：

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

使用方法

搜索日志

当用户提供标识符、端点、消息 ID、工作流执行 ID、Webhook 送达 ID、请求 ID，或提出「发生了什么？」这类模糊的调试问题时，优先搜索 Logs。

首选方式：

1. 搜索当前项目：kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json
2. 如果精确搜索没有结果，在确认没有日志之前，使用 --period 7d 重试。
3. 对范围较广的错误扫描，添加 --problems-only；重建精确时间线时，不要添加此选项。
4. 仅在需要有意缩小搜索范围时，添加明确的筛选条件：
   • 工作流执行：kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --output json
   • API 端点/状态：kapso logs search --source external_api_log --filter endpoint_contains=/messages --filter response_status=500 --period 24h --output json
   • WhatsApp 消息 ID：kapso logs search --query "wamid..." --source whatsapp_webhook_event --filter whatsapp_message_id=wamid... --period 7d --output json
   • Webhook 送达：kapso logs search --source webhook_delivery --filter webhook_id=<webhook-id> --period 24h --output json

备用方式：

1. 通过 Platform API 搜索：node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20
2. 使用重复的标志传入筛选条件：node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d
3. 查看可用的来源和筛选选项：node scripts/log-search.js --catalog true

Logs 来源包括 external_api_log、whatsapp_webhook_event、flow_event 和 webhook_delivery。Platform API 备用方式会返回 API 密钥所属项目的已索引 Logs 负载，并且要求启用 Logs 和 Elasticsearch。

调查消息送达情况

首选方式：

1. 优先搜索 WAMID 或客户电话号码：kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json
2. 解析号码：kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
3. 列出最近的消息：kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json
4. 检查特定消息：kapso whatsapp messages get <message-id> --phone-number-id <id> --output json
5. 检查对话：kapso whatsapp conversations list --phone-number "<display-number>" --output json

备用方式：

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. 确认项目和号码状态：kapso status
2. 检查号码健康状态：kapso whatsapp numbers health --phone-number "<display-number>" --output human
3. 搜索最近的问题日志：kapso logs search --problems-only --period 24h --source all --limit 20 --output json
4. 相关时检查模板：kapso whatsapp templates list --phone-number "<display-number>" --output json

备用方式：

1. 搜索 Logs：node scripts/log-search.js --problems-only true --period 24h --limit 20
2. 消息错误：node scripts/errors.js
3. API 日志：node scripts/api-logs.js
4. Webhook 送达记录：node scripts/webhook-deliveries.js

运行健康检查

首选方式：

1. 项目概览：kapso status
2. 电话号码健康状况：kapso whatsapp numbers health --phone-number "<display-number>" --output human

备用方式：

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

脚本

消息

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

错误和日志

脚本	用途
log-search.js	搜索 API、Meta webhook、工作流和 webhook 投递来源的日志
errors.js	列出消息错误
api-logs.js	列出外部 API 日志
webhook-deliveries.js	列出 webhook 投递尝试

健康状况

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

OpenAPI

脚本	用途
openapi-explore.mjs	探索 OpenAPI（search/op/schema/where）

安装依赖（仅需一次）：

npm i

示例：

node scripts/openapi-explore.mjs --spec platform search "webhook deliveries"
node scripts/openapi-explore.mjs --spec platform op listWebhookDeliveries
node scripts/openapi-explore.mjs --spec platform schema WebhookDelivery

注意事项

• 设置 webhook（创建/更新/删除、签名验证、事件类型）时，请使用 integrate-whatsapp。
• 定义 Project Event、设置事件触发的工作流，或更改 emit_event 图时，请使用 automate-whatsapp。
• 深入调试前，优先将显示电话号码解析为规范的 phone_number_id。
• 需要关联消息、工作流、API 调用和 webhook 投递时，优先搜索 Logs，而不是使用较早的单资源日志端点。
• CLI 不可用，或需要检查 API 日志或 webhook 投递时，请将这些脚本作为备用方式。

参考资料

• references/message-debugging-reference.md - 消息调试指南
• references/triage-reference.md - 错误分类处理指南
• references/health-reference.md - 健康检查指南

相关技能

• integrate-whatsapp - 入门配置、webhook、消息、模板、流程
• automate-whatsapp - 工作流、Agent 和自动化

[observe-whatsapp file map]|root: .
|.:{package.json,SKILL.md}
|assets:{health-example.json,message-debugging-example.json,triage-example.json}
|references:{health-reference.md,message-debugging-reference.md,triage-reference.md}
|scripts:{api-logs.js,errors.js,log-search.js,lookup-conversation.js,message-details.js,messages.js,openapi-explore.mjs,overview.js,webhook-deliveries.js,whatsapp-health.js}
|scripts/lib/messages:{args.js,kapso-api.js}
|scripts/lib/status:{args.js,kapso-api.js}
|scripts/lib/triage:{args.js,kapso-api.js}