Agent-skills observe-whatsapp

Observe and troubleshoot WhatsApp in Kapso: debug message delivery, inspect webhook deliveries/retries, triage API errors, and run health checks. Use when investigating production issues, message failures, or webhook delivery problems.

install

source · Clone the upstream repo

git clone https://github.com/gokapso/agent-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/gokapso/agent-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/observe-whatsapp" ~/.claude/skills/gokapso-agent-skills-observe-whatsapp && rm -rf "$T"

manifest: skills/observe-whatsapp/SKILL.md

source content

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}