Observe Whatsapp

Observe WhatsApp

When to use

Use this skill for operational diagnostics: unified project log search, message delivery investigation, webhook delivery debugging, error triage, workflow event correlation and execution investigation, 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

Search logs

Use Logs search first when the user gives an identifier, endpoint, message ID, workflow execution ID, webhook delivery ID, request ID, or a vague "what happened?" debugging prompt.

Preferred path:

1. Search the current project: kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json
2. If the exact search is empty, retry with --period 7d before concluding there are no logs.
3. Add --problems-only for broad error scans; leave it off when reconstructing an exact timeline.
4. Add explicit filters only when they intentionally narrow the search:
   • Workflow execution: kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --output json
   • API endpoint/status: kapso logs search --source external_api_log --filter endpoint_contains=/messages --filter response_status=500 --period 24h --output json
   • WhatsApp message ID: kapso logs search --query "wamid..." --source whatsapp_webhook_event --filter whatsapp_message_id=wamid... --period 7d --output json
   • Webhook delivery: kapso logs search --source webhook_delivery --filter webhook_id=<webhook-id> --period 24h --output json

Fallback path:

1. Search via Platform API: node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20
2. Use filters with repeated flags: node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d
3. Discover source and filter options: node scripts/log-search.js --catalog true

Logs sources are external_api_log, whatsapp_webhook_event, flow_event, and webhook_delivery. The Platform API fallback returns indexed Logs payloads for the API-key project and requires Logs and Elasticsearch to be enabled.

Investigate message delivery

Preferred path:

1. Search the WAMID or customer phone first: kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json
2. Resolve the number: kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
3. List recent messages: kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json
4. Inspect a specific message: kapso whatsapp messages get <message-id> --phone-number-id <id> --output json
5. Inspect the conversation: kapso whatsapp conversations list --phone-number "<display-number>" --output json

Fallback path:

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

Preferred path:

1. Search cross-source logs first when you have a request ID, wamid.*, endpoint, webhook ID, workflow execution ID, phone number, or recent time window: kapso logs search --query "<identifier-or-text>" --period 24h --limit 20 --output json
2. Narrow by source when known: kapso logs search --source external_api_log --query "/messages" --problems-only --output json
3. Confirm project and number state: kapso status
4. Run number health: kapso whatsapp numbers health --phone-number "<display-number>" --output human
5. Inspect related templates when relevant: kapso whatsapp templates list --phone-number "<display-number>" --output json

MCP path:

• If the Kapso MCP server is connected, use search_logs for cross-resource diagnostics before older narrow tools.
• Good starting inputs: query, period, source, problems_only, limit, and filters as {key, value} entries.
• Sources: external_api_log, whatsapp_webhook_event, flow_event, webhook_delivery.

Fallback path:

1. Unified log search: node scripts/log-search.js --query "<identifier-or-text>" --period 24h --limit 20
2. Discover log-search filters and sources: node scripts/log-search-catalog.js
3. Message errors: node scripts/errors.js
4. API logs: node scripts/api-logs.js
5. Webhook deliveries: node scripts/webhook-deliveries.js

Use direct API filters when you know the indexed field:

node scripts/log-search.js --source api --problems-only true --filter response_status=500 --filter endpoint_contains=/messages
node scripts/log-search.js --source workflows --filter flow_execution_id=exec_123 --limit 20

Run health checks

Preferred path:

1. Project overview: kapso status
2. Phone number health: kapso whatsapp numbers health --phone-number "<display-number>" --output human

Fallback path:

1. Project overview: node scripts/overview.js
2. Phone number health: node scripts/whatsapp-health.js --phone-number-id <id>

Scripts

Messages

Errors and logs

Health

OpenAPI

Install deps (once):

npm i

Examples:

node scripts/openapi-explore.mjs --spec platform search "log search"
node scripts/openapi-explore.mjs --spec platform op searchLogs
node scripts/openapi-explore.mjs --spec platform op getLogSearchCatalog

Notes

• For webhook setup (create/update/delete, signature verification, event types), use integrate-whatsapp.
• For Project Event definitions, event-triggered workflow setup, or emit_event graph changes, use automate-whatsapp.
• Prefer resolving a display phone number to the canonical phone_number_id before deep debugging.
• Prefer unified log search before older narrow tools when the user gives a request ID, WhatsApp wamid.*, endpoint, webhook ID, workflow execution ID, phone ID, conversation, or recent incident window.
• Keep the scripts as the fallback path when the CLI or MCP is unavailable.

References

• references/message-debugging-reference.md - Message debugging guide
• references/log-search-reference.md - Unified log search 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,log-search-reference.md,message-debugging-reference.md,triage-reference.md}
|scripts:{api-logs.js,errors.js,log-search-catalog.js,log-search.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}