---

name: whatsapp-logs description: Read and analyze WhatsApp bot logs for debugging, monitoring, and troubleshooting. Use this skill when asked to "check WhatsApp logs", "debug the bot", "find WhatsApp errors", "analyze bot performance", "trace a message", "why did the bot fail", or any investigation of WhatsApp bot behavior. Covers log file locations, JSON log format, message tracing, error analysis, and common debugging patterns.

WhatsApp Bot Log Analysis

Log Files

Get today's logs:

Copyls -la logs/whatsapp-*.log 2>/dev/null | tail -5

JSON Log Structure

Copy{
  "timestamp": "2026-01-04 14:30:45.123",
  "level": "INFO",
  "message": "Received message",
  "service": "whatsapp",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "handleMessage",
  "durationMs": 1234,
  "meta": {
    "from": "972501234567",
    "isGroup": false,
    "textPreview": "What's in progress?"
  }
}

Key Fields:

• service - Always "whatsapp" for bot logs
• correlationId - UUID linking logs for a single request
• operation - What operation was performed
• durationMs - Time taken in milliseconds
• meta.from - Sender phone number
• meta.isGroup - Whether message came from a group

Quick Commands

View Recent Activity

Copytail -50 logs/whatsapp-debug-$(date +%Y-%m-%d).log | jq .

Check Errors Today

Copycat logs/whatsapp-error-$(date +%Y-%m-%d).log 2>/dev/null | jq .

Watch Logs Real-Time

Copytail -f logs/whatsapp-debug-$(date +%Y-%m-%d).log | jq .

Find Messages From a Phone Number

Copygrep '"from":"972501234567"' logs/whatsapp-debug-*.log | jq .

Check Connection Status

Copygrep -E "(Connected|Disconnected|reconnect)" logs/whatsapp-debug-*.log | tail -10 | jq .

Common Debugging Scenarios

Bot Not Responding

Copy# Check if messages are being received
grep "Received message" logs/whatsapp-debug-$(date +%Y-%m-%d).log | tail -5 | jq '{time: .timestamp, from: .meta.from, text: .meta.textPreview}'

# Check for processing errors
grep -E '"level":"ERROR"' logs/whatsapp-debug-$(date +%Y-%m-%d).log | tail -10 | jq .

Connection Issues

Copy# Check connection events
grep -E "(connection|reconnect|disconnect)" logs/whatsapp-debug-*.log | jq '{time: .timestamp, msg: .message}'

# Check QR code events
grep "QR" logs/whatsapp-debug-*.log | tail -5 | jq .

Voice Message Issues

Copy# Check transcription activity
grep -E "(transcri|voice|audio)" logs/whatsapp-debug-*.log | jq '{time: .timestamp, msg: .message, duration: .meta.duration}'

Group Message Issues

Copy# Check group activity
grep '"isGroup":true' logs/whatsapp-debug-*.log | tail -10 | jq '{time: .timestamp, group: .meta.groupId, from: .meta.from}'

# Check group metadata fetching
grep "group.*metadata" logs/whatsapp-debug-*.log | jq .

Image Processing Issues

Copy# Check image downloads
grep -E "(image|media)" logs/whatsapp-debug-*.log | jq '{time: .timestamp, msg: .message, size: .meta.size}'

Agent/Claude Issues

Copy# Check agent processing
grep '"service":"whatsapp"' logs/whatsapp-debug-*.log | grep -E "(process|agent)" | jq .

Trace a Single Request

1. Find the correlation ID from an error or message:

Copygrep "Received message" logs/whatsapp-debug-$(date +%Y-%m-%d).log | tail -1 | jq .correlationId

1. Trace all related logs:

Copygrep "CORRELATION_ID_HERE" logs/whatsapp-debug-*.log | jq .

Performance Analysis

Find Slow Operations (>5s)

Copygrep durationMs logs/whatsapp-debug-*.log | jq 'select(.durationMs > 5000) | {msg: .message, duration: .durationMs}'

Message Processing Times

Copygrep "Sent response" logs/whatsapp-debug-*.log | jq '{time: .timestamp, duration: .meta.responseTime}'

Count Messages Today

Copygrep "Received message" logs/whatsapp-debug-$(date +%Y-%m-%d).log | wc -l

Error Rate

Copyecho "Errors: $(cat logs/whatsapp-error-$(date +%Y-%m-%d).log 2>/dev/null | wc -l)"
echo "Total: $(cat logs/whatsapp-debug-$(date +%Y-%m-%d).log | wc -l)"

Log Rotation Configuration

Log files are named: whatsapp-debug-YYYY-MM-DD.log Old logs are compressed: whatsapp-debug-YYYY-MM-DD.log.gz

Reading Compressed Logs

Copy# Read compressed log
zcat logs/whatsapp-debug-2026-01-01.log.gz | jq . | head -50

# Search in compressed logs
zgrep "error" logs/whatsapp-debug-*.log.gz | head -20

Log Level Configuration

Set via LOG_LEVEL environment variable when starting the bot:

• error - Only errors
• warn - Errors and warnings
• info - Normal operation (default)
• debug - Verbose debugging

CopyLOG_LEVEL=debug npm run whatsapp

Debugging Tips

1. Start with errors - Check whatsapp-error-*.log first
2. Use correlation IDs - Links all logs for a single message flow
3. Check timestamps - Gaps indicate hanging operations
4. Look at meta field - Contains phone numbers, group IDs, message previews
5. Use jq for filtering - JSON format enables powerful queries
6. Compare durations - Sudden increases indicate API issues
7. Check both log files - Debug logs show full flow, error logs show failures