observe-whatsapp

Name: observe-whatsapp
Author: gokapso

2.1kinstalls19forks

How to install observe-whatsapp?

gokapso/agent-skills/observe-whatsapp

$npx -y skills add gokapso/agent-skills --skill observe-whatsapp

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Observe WhatsApp
2
3	## When to use
4
5	Use this skill for operational diagnostics: Logs search, message delivery investigation, webhook delivery debugging, error triage, workflow event correlation, and WhatsApp health checks.
6
7	## Setup
8
9	Preferred path:
10	- Kapso CLI installed and authenticated (`kapso login`)
11	- Start with `kapso status` to confirm project access and available WhatsApp numbers
12
13	Fallback path:
14	Env vars:
15	- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
16	- `KAPSO_API_KEY`
17
18	## How to
19
20	### Search logs
21
22	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.
23
24	Preferred path:
25	1. Search the current project: `kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json`
26	2. If the exact search is empty, retry with `--period 7d` before concluding there are no logs.
27	3. Add `--problems-only` for broad error scans; leave it off when reconstructing an exact timeline.
28	4. Add explicit filters only when they intentionally narrow the search:
29	- Workflow execution: `kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --output json`
30	- API endpoint/status: `kapso logs search --source external_api_log --filter endpoint_contains=/messages --filter response_status=500 --period 24h --output json`
31	- WhatsApp message ID: `kapso logs search --query "wamid..." --source whatsapp_webhook_event --filter whatsapp_message_id=wamid... --period 7d --output json`
32	- Webhook delivery: `kapso logs search --source webhook_delivery --filter webhook_id=<webhook-id> --period 24h --output json`
33
34	Fallback path:
35	1. Search via Platform API: `node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20`
36	2. Use filters with repeated flags: `node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d`
37	3. Discover source and filter options: `node scripts/log-search.js --catalog true`
38
39	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.
40
41	### Investigate message delivery
42
43	Preferred path:
44	1. Search the WAMID or customer phone first: `kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json`
45	2. Resolve the number: `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`
46	3. List recent messages: `kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json`
47	4. Inspect a specific message: `kapso whatsapp messages get <message-id> --phone-number-id <id> --output json`
48	5. Inspect the conversation: `kapso whatsapp conversations list --phone-number "<display-number>" --output json`
49
50	Fallback path:
51	1. List messages: `node scripts/messages.js --phone-number-id <id>`
52	2. Inspect message: `node scripts/message-details.js --message-id <id>`
53	3. Find conversation: `node scripts/lookup-conversation.js --phone-number <e164>`
54
55	### Triage errors
56
57	Preferred path:
58	1. Confirm project and number state: `kapso status`
59	2. Run number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
60	3. Search recent problem logs: `kapso logs search --problems-only --period 24h --source all --limit 20 --output json`
61	4. Inspect related templates when relevant: `kapso whatsapp templates list --phone-number "<display-number>" --output json`
62
63	Fallback path:
64	1. Logs search: `node scripts/log-search.js --problems-only true --period 24h --limit 20`
65	2. Message errors: `node scripts/errors.js`
66	3. API logs: `node scripts/api-logs.js`
67	4. Webhook deliveries: `node scripts/webhook-deliveries.js`
68
69	### Run health checks
70
71	Preferred path:
72	1. Project overview: `kapso status`
73	2. Phone number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
74
75	Fallback path:
76	1. Project overview: `node scripts/overview.js`
77	2. Phone number health: `node scripts/whatsapp-health.js --phone-number-id <id>`
78
79	## Scripts
80
81	### Messages
82
83	\| Script \| Purpose \|
84	\|--------\|---------\|
85	\| `messages.js` \| List messages \|
86	\| `message-details.js` \| Get message details \|
87	\| `lookup-conversation.js` \| Find conversation by phone or ID \|
88
89	### Errors and logs
90
91	\| Script \| Purpose \|
92	\|--------\|---------\|
93	\| `log-search.js` \| Search Logs across API, Meta webhook, workflow, and webhook-delivery sources \|
94	\| `errors.js` \| List message errors \|
95	\| `api-logs.js` \| List ex

People who liked this also viewed

6 picks

Type

observe-whatsapp

2.1kinstalls19forks

View on GitHub

How to install observe-whatsapp?

gokapso/agent-skills/observe-whatsapp

$npx -y skills add gokapso/agent-skills --skill observe-whatsapp

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Observe WhatsApp
2
3	## When to use
4
5	Use this skill for operational diagnostics: Logs search, message delivery investigation, webhook delivery debugging, error triage, workflow event correlation, and WhatsApp health checks.
6
7	## Setup
8
9	Preferred path:
10	- Kapso CLI installed and authenticated (`kapso login`)
11	- Start with `kapso status` to confirm project access and available WhatsApp numbers
12
13	Fallback path:
14	Env vars:
15	- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
16	- `KAPSO_API_KEY`
17
18	## How to
19
20	### Search logs
21
22	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.
23
24	Preferred path:
25	1. Search the current project: `kapso logs search --query "<id-or-text>" --period 24h --source all --limit 20 --output json`
26	2. If the exact search is empty, retry with `--period 7d` before concluding there are no logs.
27	3. Add `--problems-only` for broad error scans; leave it off when reconstructing an exact timeline.
28	4. Add explicit filters only when they intentionally narrow the search:
29	- Workflow execution: `kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --output json`
30	- API endpoint/status: `kapso logs search --source external_api_log --filter endpoint_contains=/messages --filter response_status=500 --period 24h --output json`
31	- WhatsApp message ID: `kapso logs search --query "wamid..." --source whatsapp_webhook_event --filter whatsapp_message_id=wamid... --period 7d --output json`
32	- Webhook delivery: `kapso logs search --source webhook_delivery --filter webhook_id=<webhook-id> --period 24h --output json`
33
34	Fallback path:
35	1. Search via Platform API: `node scripts/log-search.js --query "<id-or-text>" --period 24h --source all --limit 20`
36	2. Use filters with repeated flags: `node scripts/log-search.js --source flow_event --filter flow_execution_id=<execution-id> --period 7d`
37	3. Discover source and filter options: `node scripts/log-search.js --catalog true`
38
39	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.
40
41	### Investigate message delivery
42
43	Preferred path:
44	1. Search the WAMID or customer phone first: `kapso logs search --query "<wamid-or-phone>" --period 7d --source all --limit 20 --output json`
45	2. Resolve the number: `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`
46	3. List recent messages: `kapso whatsapp messages list --phone-number "<display-number>" --limit 50 --output json`
47	4. Inspect a specific message: `kapso whatsapp messages get <message-id> --phone-number-id <id> --output json`
48	5. Inspect the conversation: `kapso whatsapp conversations list --phone-number "<display-number>" --output json`
49
50	Fallback path:
51	1. List messages: `node scripts/messages.js --phone-number-id <id>`
52	2. Inspect message: `node scripts/message-details.js --message-id <id>`
53	3. Find conversation: `node scripts/lookup-conversation.js --phone-number <e164>`
54
55	### Triage errors
56
57	Preferred path:
58	1. Confirm project and number state: `kapso status`
59	2. Run number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
60	3. Search recent problem logs: `kapso logs search --problems-only --period 24h --source all --limit 20 --output json`
61	4. Inspect related templates when relevant: `kapso whatsapp templates list --phone-number "<display-number>" --output json`
62
63	Fallback path:
64	1. Logs search: `node scripts/log-search.js --problems-only true --period 24h --limit 20`
65	2. Message errors: `node scripts/errors.js`
66	3. API logs: `node scripts/api-logs.js`
67	4. Webhook deliveries: `node scripts/webhook-deliveries.js`
68
69	### Run health checks
70
71	Preferred path:
72	1. Project overview: `kapso status`
73	2. Phone number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
74
75	Fallback path:
76	1. Project overview: `node scripts/overview.js`
77	2. Phone number health: `node scripts/whatsapp-health.js --phone-number-id <id>`
78
79	## Scripts
80
81	### Messages
82
83	\| Script \| Purpose \|
84	\|--------\|---------\|
85	\| `messages.js` \| List messages \|
86	\| `message-details.js` \| Get message details \|
87	\| `lookup-conversation.js` \| Find conversation by phone or ID \|
88
89	### Errors and logs
90
91	\| Script \| Purpose \|
92	\|--------\|---------\|
93	\| `log-search.js` \| Search Logs across API, Meta webhook, workflow, and webhook-delivery sources \|
94	\| `errors.js` \| List message errors \|
95	\| `api-logs.js` \| List ex

People who liked this also viewed

6 picks

Type