Observe WhatsApp
When to use
Use this skill for operational diagnostics: message delivery investigation, webhook delivery debugging, error triage, and WhatsApp health checks.
Setup
Preferred path:
- Kapso CLI installed and authenticated (
kapso login) - Start with
kapso statusto confirm project access and available WhatsApp numbers
Fallback path: Env vars:
KAPSO_API_BASE_URL(host only, no/platform/v1)KAPSO_API_KEY
How to
Investigate message delivery
Preferred path:
- Resolve the number:
kapso whatsapp numbers resolve --phone-number "<display-number>" --output json - List recent messages:
kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json - Inspect a specific message:
kapso whatsapp messages get <message-id> --phone-number-id <id> --output json - Inspect the conversation:
kapso whatsapp conversations list --phone-number "<display-number>" --output json
Fallback path:
- List messages:
node scripts/messages.js --phone-number-id <id> - Inspect message:
node scripts/message-details.js --message-id <id> - Find conversation:
node scripts/lookup-conversation.js --phone-number <e164>
Triage errors
Preferred path:
- Confirm project and number state:
kapso status - Run number health:
kapso whatsapp numbers health --phone-number "<display-number>" --output human - Inspect related templates when relevant:
kapso whatsapp templates list --phone-number "<display-number>" --output json
Fallback path:
- Message errors:
node scripts/errors.js - API logs:
node scripts/api-logs.js - Webhook deliveries:
node scripts/webhook-deliveries.js
Run health checks
Preferred path:
- Project overview:
kapso status - Phone number health:
kapso whatsapp numbers health --phone-number "<display-number>" --output human
Fallback path:
- Project overview:
node scripts/overview.js - Phone number health:
node scripts/whatsapp-health.js --phone-number-id <id>
Scripts
Messages
| Script | Purpose |
|---|---|
messages.js | List messages |
message-details.js | Get message details |
lookup-conversation.js | Find conversation by phone or ID |
Errors and logs
| Script | Purpose |
|---|---|
errors.js | List message errors |
api-logs.js | List external API logs |
webhook-deliveries.js | List webhook delivery attempts |
Health
| Script | Purpose |
|---|---|
overview.js | Project overview |
whatsapp-health.js | Phone number health check |
OpenAPI
| Script | Purpose |
|---|---|
openapi-explore.mjs | Explore OpenAPI (search/op/schema/where) |
Install deps (once):
npm iExamples:
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 WebhookDeliveryNotes
- For webhook setup (create/update/delete, signature verification, event types), use
integrate-whatsapp. - Prefer resolving a display phone number to the canonical
phone_number_idbefore deep debugging. - Keep the scripts as the fallback path when the CLI is unavailable or when you need API-log or webhook-delivery inspection.
References
- references/message-debugging-reference.md - Message debugging guide
- references/triage-reference.md - Error triage guide
- references/health-reference.md - Health check guide
Related skills
integrate-whatsapp- Onboarding, webhooks, messaging, templates, flowsautomate-whatsapp- Workflows, agents, and automations
<!-- FILEMAP:BEGIN -->
[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,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}<!-- FILEMAP:END -->
