Observe and troubleshoot WhatsApp in Kapso: debug message delivery, inspect webhook deliveries/retries, triage API errors, and run health checks. Use when…
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 status to 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 i
Examples:
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
Notes
For webhook setup (create/update/delete, signature verification, event types), use integrate-whatsapp.
Prefer resolving a display phone number to the canonical phone_number_id before 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, flows
automate-whatsapp - Workflows, agents, and automations
[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}don't have the plugin yet? install it then click "run inline in claude" again.