name: kapso-ops
description: Operate and troubleshoot Kapso projects. Manage webhooks, debug message delivery, inspect API errors, and run health checks. Use when diagnosing issues, setting up webhooks, or investigating message failures.

Kapso Ops

When to use

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

Setup

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

How to

Set up a webhook

1. Create: node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>
2. Verify signature handling (see references/webhooks-overview.md)
3. Test: node scripts/test.js --webhook-id <id>

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

Webhooks

Common flags for create/update:
- --url <https://...> - Webhook URL
- --events <csv> - Event types (comma-separated)
- --kind <kapso|meta> - Webhook type
- --payload-version <v1|v2> - Payload format (v2 recommended)
- --buffer-enabled <true|false> - Enable buffering
- --active <true|false> - Enable/disable

Messages

Errors and logs

Health

Notes

• Use config-level webhooks for whatsapp.message.* events
• Payload version v2 is recommended for new integrations
• Meta webhooks provide raw payloads; Kapso webhooks support buffering

References

• references/webhooks-reference.md - Webhook API reference
• references/webhooks-overview.md - Webhook concepts and setup
• references/webhooks-event-types.md - Available event types
• references/message-debugging-reference.md - Message debugging guide
• references/triage-reference.md - Error triage guide
• references/health-reference.md - Health check guide

Related skills

• kapso-automation - Automation and functions
• whatsapp-messaging - WhatsApp messaging
• kapso-api - Platform API and customers