How do I set up the environment?

Set KAPSO_API_BASE_URL (host only) and KAPSO_API_KEY as environment variables before running any scripts.

How do I find a conversation by phone?

Use node scripts/lookup-conversation.js --phone-number to locate the conversation and then reference its message history.

What should I do if webhook deliveries show errors?

Use node scripts/webhook-deliveries.js to list deliveries, then correlate with errors.js and api-logs.js to triage root causes.

observe-whatsapp

Scanned

npx machina-cli add skill gokapso/agent-skills/observe-whatsapp --openclaw

Files (1)

SKILL.md

3.2 KB

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

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

Message errors: node scripts/errors.js
API logs: node scripts/api-logs.js
Webhook deliveries: node scripts/webhook-deliveries.js

Run health checks

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.

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}

Source

git clone https://github.com/gokapso/agent-skills/blob/master/skills/observe-whatsapp/SKILL.mdView on GitHub

Overview

Observe-whatsapp enables operational diagnostics for WhatsApp in Kapso, including message delivery debugging, webhook delivery/retry inspection, API error triage, and health checks. It’s designed for use when investigating production issues, message failures, or webhook problems.

How This Skill Works

The skill exposes a set of node scripts (messages.js, message-details.js, lookup-conversation.js, errors.js, api-logs.js, webhook-deliveries.js, overview.js, whatsapp-health.js) that call the Kapso API using KAPSO_API_BASE_URL and KAPSO_API_KEY. Run the scripts to fetch messages, errors, webhook deliveries, and health data and then correlate results to triage issues.

When to Use It

Investigating production WhatsApp message delivery failures
Debugging webhook delivery problems and retries
Triage API errors seen in the WhatsApp integration
Running health checks on a project or phone number
Exploring OpenAPI capabilities to query platform data

Quick Start

Step 1: Set environment variables KAPSO_API_BASE_URL and KAPSO_API_KEY
Step 2: Install dependencies with npm i
Step 3: Run a workflow, e.g. node scripts/messages.js --phone-number-id <id> and follow with message-details.js as needed

Best Practices

Set KAPSO_API_BASE_URL and KAPSO_API_KEY before starting
Start with overview.js to get a project health snapshot
Use lookup-conversation.js to map messages to conversations
Correlate outputs from errors.js, api-logs.js, and webhook-deliveries.js
Document findings and share outputs with your team

Example Use Cases

Diagnose a failed outbound message by listing messages for a phone-number-id and inspecting message-details
Identify repeated webhook delivery failures by listing webhook deliveries and reviewing retry patterns
Triage API errors by listing api-logs and errors for the affected window
Run project overview to uncover bottlenecks and health issues
Perform a phone-number health check with whatsapp-health.js --phone-number-id <id>

Frequently Asked Questions

Add this skill to your agents