# Observe Whatsapp

> Monitor and debug WhatsApp webhook delivery. Use when user wants to: list event logs, filter events by type/status/date/errors, inspect event payloads, check channel WABA health (quality rating, messaging tier, connection status), upload/get/delete media files. Do not use for sending messages or managing channels. Useful for troubleshooting delivery failures.

- Skill: `zaphook/observe-whatsapp` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add zaphook/observe-whatsapp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zaphook/observe-whatsapp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: zaphook (https://skillmd.com/u/zaphook)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zaphook/observe-whatsapp

---


# Observe WhatsApp

Base URL: `https://api.zaphook.cloud`
Auth: `Authorization: Bearer zph_...`

## Commands

### List Events
```bash
node scripts/list-events.mjs [--channel-id <uuid>] [--event-type text|image|audio|status] [--delivery-status delivered|failed|pending|logged|retrying] [--has-errors true|false] [--start-date 2024-01-01T00:00:00Z] [--end-date 2024-01-31T23:59:59Z] [--limit 50] [--offset 0]
```
GET /api/public/v1/events

Response:
```json
{
  "data": {
    "events": [{
      "id": "uuid",
      "channel_id": "uuid",
      "event_type": "text",
      "event_id": "wamid.abc123",
      "delivery_status": "delivered",
      "destination_url": "https://example.com/webhook",
      "response_code": 200,
      "retry_count": 0,
      "processing_time_ms": 150,
      "created_at": "2024-01-15T10:30:00+00:00"
    }],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

Note: Events are webhook delivery logs (incoming webhooks forwarded to destinations). They track if the event was successfully delivered to configured destinations. Status callbacks (sent/delivered/read) from Meta appear as event_type "status".

### Get Event Detail
```bash
node scripts/get-event.mjs --event-id <uuid>
```
GET /api/public/v1/events/{event_id}

Returns full payload, processed_payload, response_body, and delivery metadata.

### Channel Health (WABA Status)
```bash
node scripts/channel-health.mjs --channel-id <uuid>
```
GET /api/public/v1/channels/{channel_id}/status

Returns: quality_rating, messaging_limit_tier, status (CONNECTED/DISCONNECTED), verified_name, platform_type, is_active, channel_type.

### Upload Media
```bash
node scripts/upload-media.mjs --channel-id <uuid> --file <path> --type image|video|audio|document
```
POST /api/public/v1/media/upload

### Get Media
```bash
node scripts/get-media.mjs --media-id <id> --channel-id <uuid>
```
GET /api/public/v1/media/{media_id}?channel_id=<uuid>

### Delete Media
```bash
node scripts/delete-media.mjs --media-id <id> --channel-id <uuid>
```
DELETE /api/public/v1/media/{media_id}?channel_id=<uuid>

## Debugging Workflow

1. Check channel health: `node scripts/channel-health.mjs --channel-id <id>`
2. Find failed events: `node scripts/list-events.mjs --has-errors true`
3. Inspect specific event: `node scripts/get-event.mjs --event-id <uuid>`
4. Filter by date range: `node scripts/list-events.mjs --start-date 2024-01-01T00:00:00Z --end-date 2024-01-02T00:00:00Z`

## Important Notes

- Events represent webhook delivery logs (ZapHook forwarding to your destinations)
- If events are empty but the dashboard shows activity, the channel may not have destinations configured
- Coexistence channels receive status callbacks only if Meta's webhook points to ZapHook
- Standard channels automatically receive all callbacks via their webhook_url

## Related skills

- `zaphook-api` — Channel and destination management
- `whatsapp-messaging` — Send messages and templates