Observe WhatsApp
When to use
Use this skill for operational diagnostics: Logs search, message delivery investigation, webhook delivery debugging, error triage, workflow event correlation, 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:
- Search the current project:
kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json
- If the exact search is empty, retry with
--period 7d before concluding there are no logs.
- Add
--problems-only for broad error scans; leave it off when reconstructing an exact timeline.
- 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:
- Search via Platform API:
node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20
- Use filters with repeated flags:
node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d
- 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:
- Search the WAMID or customer phone first:
kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json
- 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
- Search recent problem logs:
kapso logs search --problems-only --period 24h --source all --limit 20 --output json
- Inspect related templates when relevant:
kapso whatsapp templates list --phone-number "<display-number>" --output json
Fallback path:
- Logs search:
node scripts/log-search.js --problems-only true --period 24h --limit 20
- 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 |
log-search.js |
Search Logs across API, Meta webhook, workflow, and webhook-delivery sources |
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.
- 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 Logs search before older single-resource log endpoints when correlating across messages, workflows, API calls, and webhook deliveries.
- 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,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}
1---
2name: observe-whatsapp
3description: "Observe and troubleshoot WhatsApp in Kapso: search Logs across API, Meta webhook, workflow, and webhook-delivery events; debug message delivery; inspect webhook retries; triage API errors; and run health checks. Use when investigating production issues, message failures, workflow behavior, or webhook delivery problems."
4metadata:
5 source: https://skillmd.com/skills/gokapso/observe-whatsapp
6---
7
8# Observe WhatsApp
9
10## When to use
11
12Use this skill for operational diagnostics: Logs search, message delivery investigation, webhook delivery debugging, error triage, workflow event correlation, and WhatsApp health checks.
13
14## Setup
15
16Preferred path:
17- Kapso CLI installed and authenticated (`kapso login`)
18- Start with `kapso status` to confirm project access and available WhatsApp numbers
19
20Fallback path:
21Env vars:
22- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
23- `KAPSO_API_KEY`
24
25## How to
26
27### Search logs
28
29Use 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.
30
31Preferred path:
321. Search the current project: `kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json`
332. If the exact search is empty, retry with `--period 7d` before concluding there are no logs.
343. Add `--problems-only` for broad error scans; leave it off when reconstructing an exact timeline.
354. Add explicit filters only when they intentionally narrow the search:
36 - Workflow execution: `kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --output json`
37 - API endpoint/status: `kapso logs search --source external_api_log --filter endpoint_contains=/messages --filter response_status=500 --period 24h --output json`
38 - WhatsApp message ID: `kapso logs search --query "wamid..." --source whatsapp_webhook_event --filter whatsapp_message_id=wamid... --period 7d --output json`
39 - Webhook delivery: `kapso logs search --source webhook_delivery --filter webhook_id=<webhook-id> --period 24h --output json`
40
41Fallback path:
421. Search via Platform API: `node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20`
432. Use filters with repeated flags: `node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d`
443. Discover source and filter options: `node scripts/log-search.js --catalog true`
45
46Logs 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.
47
48### Investigate message delivery
49
50Preferred path:
511. Search the WAMID or customer phone first: `kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json`
522. Resolve the number: `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`
533. List recent messages: `kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json`
544. Inspect a specific message: `kapso whatsapp messages get <message-id> --phone-number-id <id> --output json`
555. Inspect the conversation: `kapso whatsapp conversations list --phone-number "<display-number>" --output json`
56
57Fallback path:
581. List messages: `node scripts/messages.js --phone-number-id <id>`
592. Inspect message: `node scripts/message-details.js --message-id <id>`
603. Find conversation: `node scripts/lookup-conversation.js --phone-number <e164>`
61
62### Triage errors
63
64Preferred path:
651. Confirm project and number state: `kapso status`
662. Run number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
673. Search recent problem logs: `kapso logs search --problems-only --period 24h --source all --limit 20 --output json`
684. Inspect related templates when relevant: `kapso whatsapp templates list --phone-number "<display-number>" --output json`
69
70Fallback path:
711. Logs search: `node scripts/log-search.js --problems-only true --period 24h --limit 20`
722. Message errors: `node scripts/errors.js`
733. API logs: `node scripts/api-logs.js`
744. Webhook deliveries: `node scripts/webhook-deliveries.js`
75
76### Run health checks
77
78Preferred path:
791. Project overview: `kapso status`
802. Phone number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
81
82Fallback path:
831. Project overview: `node scripts/overview.js`
842. Phone number health: `node scripts/whatsapp-health.js --phone-number-id <id>`
85
86## Scripts
87
88### Messages
89
90| Script | Purpose |
91|--------|---------|
92| `messages.js` | List messages |
93| `message-details.js` | Get message details |
94| `lookup-conversation.js` | Find conversation by phone or ID |
95
96### Errors and logs
97
98| Script | Purpose |
99|--------|---------|
100| `log-search.js` | Search Logs across API, Meta webhook, workflow, and webhook-delivery sources |
101| `errors.js` | List message errors |
102| `api-logs.js` | List external API logs |
103| `webhook-deliveries.js` | List webhook delivery attempts |
104
105### Health
106
107| Script | Purpose |
108|--------|---------|
109| `overview.js` | Project overview |
110| `whatsapp-health.js` | Phone number health check |
111
112### OpenAPI
113
114| Script | Purpose |
115|--------|---------|
116| `openapi-explore.mjs` | Explore OpenAPI (search/op/schema/where) |
117
118Install deps (once):
119```bash
120npm i
121```
122
123Examples:
124```bash
125node scripts/openapi-explore.mjs --spec platform search "webhook deliveries"
126node scripts/openapi-explore.mjs --spec platform op listWebhookDeliveries
127node scripts/openapi-explore.mjs --spec platform schema WebhookDelivery
128```
129
130## Notes
131
132- For webhook setup (create/update/delete, signature verification, event types), use `integrate-whatsapp`.
133- For Project Event definitions, event-triggered workflow setup, or `emit_event` graph changes, use `automate-whatsapp`.
134- Prefer resolving a display phone number to the canonical `phone_number_id` before deep debugging.
135- Prefer Logs search before older single-resource log endpoints when correlating across messages, workflows, API calls, and webhook deliveries.
136- Keep the scripts as the fallback path when the CLI is unavailable or when you need API-log or webhook-delivery inspection.
137
138## References
139
140- [references/message-debugging-reference.md](references/message-debugging-reference.md) - Message debugging guide
141- [references/triage-reference.md](references/triage-reference.md) - Error triage guide
142- [references/health-reference.md](references/health-reference.md) - Health check guide
143
144## Related skills
145
146- `integrate-whatsapp` - Onboarding, webhooks, messaging, templates, flows
147- `automate-whatsapp` - Workflows, agents, and automations
148
149<!-- FILEMAP:BEGIN -->
150```text
151[observe-whatsapp file map]|root: .
152|.:{package.json,SKILL.md}
153|assets:{health-example.json,message-debugging-example.json,triage-example.json}
154|references:{health-reference.md,message-debugging-reference.md,triage-reference.md}
155|scripts:{api-logs.js,errors.js,log-search.js,lookup-conversation.js,message-details.js,messages.js,openapi-explore.mjs,overview.js,webhook-deliveries.js,whatsapp-health.js}
156|scripts/lib/messages:{args.js,kapso-api.js}
157|scripts/lib/status:{args.js,kapso-api.js}
158|scripts/lib/triage:{args.js,kapso-api.js}
159```
160<!-- FILEMAP:END -->