home / skills / gokapso / agent-skills / observe-whatsapp

observe-whatsapp skill

safe

/skills/observe-whatsapp

This skill helps diagnose WhatsApp issues by inspecting messages, errors, webhooks, and health checks within Kapso.

This is most likely a fork of the observe-whatsapp skill from xfstudio

npx playbooks add skill gokapso/agent-skills --skill observe-whatsapp

Review the files below or copy the command above to add this skill to your agents.

Files (23)

SKILL.md

3.2 KB

---
name: observe-whatsapp
description: "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."
---

# Observe WhatsApp

## When to use

Use this skill for operational diagnostics: message delivery investigation, webhook delivery debugging, error triage, and WhatsApp health checks.

## Setup

Env vars:
- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
- `KAPSO_API_KEY`

## How to

### Investigate message delivery

1. List messages: `node scripts/messages.js --phone-number-id <id>`
2. Inspect message: `node scripts/message-details.js --message-id <id>`
3. Find conversation: `node scripts/lookup-conversation.js --phone-number <e164>`

### Triage errors

1. Message errors: `node scripts/errors.js`
2. API logs: `node scripts/api-logs.js`
3. Webhook deliveries: `node scripts/webhook-deliveries.js`

### Run health checks

1. Project overview: `node scripts/overview.js`
2. 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):
```bash
npm i
```

Examples:
```bash
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`.

## References

- [references/message-debugging-reference.md](references/message-debugging-reference.md) - Message debugging guide
- [references/triage-reference.md](references/triage-reference.md) - Error triage guide
- [references/health-reference.md](references/health-reference.md) - Health check guide

## Related skills

- `integrate-whatsapp` - Onboarding, webhooks, messaging, templates, flows
- `automate-whatsapp` - Workflows, agents, and automations

<!-- FILEMAP:BEGIN -->
```text
[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 -->

Overview

This skill helps observe and troubleshoot WhatsApp usage in Kapso. It provides scripts and checks to debug message delivery, inspect webhook deliveries and retries, triage API errors, and run health checks for phone numbers and projects. Use it during production incidents or routine operational checks to quickly locate causes and next steps.

How this skill works

The skill exposes small Node.js scripts that call Kapso APIs using configured environment variables. Scripts list and inspect messages, surface message errors and API logs, enumerate webhook delivery attempts, and produce health overviews for projects and phone numbers. The commands return structured data you can use to trace message paths, identify failure reasons, and confirm system health.

When to use it

Investigating failed or delayed WhatsApp messages in production
Debugging webhook delivery, signature, or retry issues
Triage API errors and third-party integration problems
Performing routine health checks on phone numbers and project-wide status
Gathering evidence for incident reports or escalation

Best practices

Set KAPSO_API_BASE_URL and KAPSO_API_KEY in your environment before running scripts
Start with overview/health checks to narrow scope, then dig into messages and webhooks
Correlate message IDs with webhook delivery records and API logs for end-to-end tracing
Keep outputs verbatim for incident timelines and attach relevant JSON to tickets
Run scripts in a reproducible environment (node version and npm deps installed)

Example use cases

List recent messages for a phone number to find missing deliveries (messages.js)
Inspect full message details and metadata for a specific message ID (message-details.js)
Find conversation context for a phone number to confirm customer state (lookup-conversation.js)
Enumerate webhook delivery attempts and retries to spot failed callbacks (webhook-deliveries.js)
Run a phone number health check to see configuration and delivery metrics (whatsapp-health.js)

FAQ

What environment variables are required?

Set KAPSO_API_BASE_URL (host only, no /platform/v1) and KAPSO_API_KEY before running scripts.

How do I install dependencies?

Run npm i in the skill directory once to install required packages.

Which script shows API-level errors and third-party logs?

Use api-logs.js for external API logs and errors.js to list message-specific errors.