Skill: netanel-abergel/whatsapp-diagnostics (version 1.0.1)

--- name: whatsapp-diagnostics description: "Diagnose and fix WhatsApp connectivity issues for OpenClaw agents. Use when: a PA is not responding, WhatsApp shows connected but messages don't arrive, the agent is online but not replying, or troubleshooting a new agent setup." --- # WhatsApp Diagnostics Skill ## Minimum Model Any model. All diagnostics are CLI-based — follow the decision tree. --- ## Diagnostic Tree (Start Here) ``` PA not responding? │ ├─ Dashboard shows "Connected and listening"? │ ├─ YES → Check Messages count │ │ ├─ Messages = 0 → INGEST ISSUE → go to Case 2 │ │ └─ Messages > 0 → RUNTIME ISSUE → go to Case 3 │ └─ NO → CONNECTION ISSUE → go to Case 1 │ └─ Agent exists in platform? ├─ YES → Follow Case 1 └─ NO → Full setup needed (see pa-onboarding skill) ``` --- ## Case 1 — Connection Issue (WhatsApp not linked) **Symptom:** Dashboard shows disconnected or no channel configured. **Fix:** 1. Open agent settings in OpenClaw platform 2. Go to Channels → WhatsApp → click **Connect** or **Re-link** 3. Scan the QR code with WhatsApp Business app 4. Confirm the phone number matches 5. Wait 30 seconds for status to update **Most common cause:** WhatsApp session expired (happens after ~14 days of inactivity or after a phone restart). --- ## Case 2 — Ingest Issue (Connected but Messages = 0) **Symptom:** Dashboard shows "Connected and listening" but message count stays at 0. **Meaning:** WhatsApp is connected at protocol level, but messages are not reaching the agent runtime. **Fix:** ```bash # Step 1: Check gateway status openclaw gateway status # Step 2: Restart the gateway openclaw gateway restart # Step 3: Send a test message, wait 30 seconds # Step 4: If count is still 0, check gateway logs openclaw gateway logs --last 50 ``` **What to look for in logs:** - `binding failed` - `session dropped` - `ingest error` If any of these appear → escalate to platform admin. This is an infrastructure issue. --- ## Case 3 — Runtime Issue (Messages arriving, no reply) **Symptom:** Message count increments, but agent doesn't respond. **Meaning:** Messages reach the agent, but the agent runtime is failing. **Fix:** ```bash # Step 1: Check for billing errors in agent log grep -i "billing\|402\|credits" ~/.openclaw/logs/agent.log | tail -20 # If billing error found → see billing-monitor skill # Step 2: Check agent status openclaw status # Step 3: Verify API key (pick your provider below) # For Anthropic: curl -s -o /dev/null -w "%{http_code}" \ -H "x-[REDACTED_SECRET]" \ -H "anthropic-version: 2023-06-01" \ https://api.anthropic.com/v1/models # For OpenAI: curl -s -o /dev/null -w "%{http_code}" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ https://api.openai.com/v1/models # For Google: curl -s -o /dev/null -w "%{http_code}" \ "https://generativelanguage.googleapis.com/v1beta/models?key=$GOOGLE_API_KEY" # Expected: 200. If 401 → invalid key. If 402 → billing error. # Step 4: Check recent runtime errors openclaw logs --last 100 | grep -i error ``` **Interpret results:** - `200` → API key is valid. Problem is elsewhere (check Step 4). - `401` → Invalid API key. Update the key in agent settings. - `402` → Billing error. Follow the billing-monitor skill. --- ## Quick Health Check Script ```bash #!/bin/bash # whatsapp-health-check.sh # Run this when the agent is unresponsive to get a quick status overview. echo "=== WhatsApp Diagnostics ===" # Check gateway status echo -n "Gateway: " openclaw gateway status 2>&1 | grep -o "running\|stopped\|error" | head -1 || echo "unknown" # Check API key — detect provider from env vars echo -n "API key: " if [ -n "${ANTHROPIC_API_KEY:-}" ]; then PROVIDER="Anthropic" # Test with a minimal request to the models endpoint STATUS=$(curl -s -o /dev/null -w "%{http_code}" \ -H "x-[REDACTED_SECRET]" \ -H "anthropic-version: 2023-06-01" \ https://api.anthropic.com/v1/models 2>/dev/null) elif [ -n "${OPENAI_API_KEY:-}" ]; then PROVIDER="OpenAI" STATUS=$(curl -s -o /dev/null -w "%{http_code}" \ -H "Authorization: Bearer ${OPENAI_API_KEY}" \ https://api.openai.com/v1/models 2>/dev/null) elif [ -n "${GOOGLE_API_KEY:-}" ]; then PROVIDER="Google" STATUS=$(curl -s -o /dev/null -w "%{http_code}" \ "https://generativelanguage.googleapis.com/v1beta/models?key=${GOOGLE_API_KEY}" 2>/dev/null) else echo "⚠️ no API key env var found" PROVIDER="" STATUS="" fi # Interpret the HTTP status code if [ -n "$STATUS" ]; then case $STATUS in 200) echo "✅ valid ($PROVIDER)" ;; 401) echo "❌ invalid key ($PROVIDER)" ;; 402) echo "⚠️ billing error ($PROVIDER) — see billing-monitor skill" ;; *) echo "? HTTP $STATUS ($PROVIDER)" ;; esac fi # Count recent errors in agent logs echo -n "Recent errors: " ERROR_COUNT=$(openclaw logs --last 100 2>/dev/null | grep -ic error || echo 0) echo "$ERROR_COUNT found" echo "=== Done ===" ``` --- ## When to Escalate to Platform Admin Escalate if: - Gateway restart does NOT fix Messages = 0 - Logs show `socket`, `binding`, or `session` errors - Multiple agents on the same server are affected at the same time Include in your escalation message: - Agent name and phone number - Time the issue started - Output of `openclaw gateway status` - Messages count shown in dashboard --- ## Prevention | Action | Why | |---|---| | Send at least one message every 7 days | Prevents WhatsApp session expiry | | Check Messages count during heartbeat | Catches ingest issues early | | Keep the phone number on record | Needed for QR re-linking | | Don't use the same number on two devices | WhatsApp only allows one active session | --- ## Cost Tips - **Very cheap:** All diagnostics use CLI + curl — no LLM tokens needed - **Small model OK:** Any model can follow this decision tree and interpret curl output - **Avoid:** Don't run diagnostics on every heartbeat — only run when the agent is not responding - **Batch:** Run the Quick Health Check script once to get all info, rather than running each check separately

path: DEPRECATED.md
content: # DEPRECATED — whatsapp-diagnostics

**Status:** Merged into whatsapp/SKILL.md
**Date:** 2026-04-02
**Reason:** Diagnostics belong as a troubleshooting appendix in the main WhatsApp skill, not standalone. One skill covers all WhatsApp concerns.
**Lesson:** Diagnostics/troubleshooting sections belong at the end of their parent skill, not in a separate file.
**Moved to:** whatsapp/SKILL.md — Section "Troubleshooting"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)