Skip to content

WhatsApp Sync

Skippy supports two-way synchronization with WhatsApp, allowing you to chat from your phone and see responses on desktop (and vice versa).

How It Works

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Desktop   │ ←─────→ │   OpenClaw  │ ←─────→ │  WhatsApp   │
│   Skippy    │         │   Gateway   │         │   Phone     │
└─────────────┘         └─────────────┘         └─────────────┘
  1. Desktop → WhatsApp: Your desktop messages are delivered to WhatsApp
  2. WhatsApp → Desktop: Phone messages appear in Skippy window
  3. Shared Session: Both use the same conversation history

Setup

1. Configure OpenClaw WhatsApp Channel

Ensure WhatsApp is connected in OpenClaw:

openclaw channels
# Should show whatsapp as available

2. Enable Sync in Skippy

Via Tray Menu:

  • Right-click tray icon
  • Check 📱 Sync to WhatsApp

Via Config:

{
    "sync_whatsapp": true,
    "whatsapp_number": "+1234567890"
}

3. Verify Connection

Send a test message from Skippy. You should receive:

  • The AI response on desktop
  • The same response on WhatsApp

Features

Two-Way Messaging

Direction What Happens
Desktop → WhatsApp Response delivered to your phone
WhatsApp → Desktop Message appears with 📱 icon

Message Prefixes

Desktop messages are tagged to identify their source:

[desktop] Your message here

WhatsApp messages appear as:

📱 WhatsApp: Message from your phone

Notification on Hidden Window

When Skippy is minimized and a WhatsApp message arrives:

  • System tray notification appears
  • "New message from WhatsApp"
  • Double-click tray to view

Configuration

config.json Settings

{
    "session_id": "skippy-desktop",
    "sync_whatsapp": true,
    "whatsapp_number": "+1234567890"
}
Setting Description
session_id Shared session identifier
sync_whatsapp Enable/disable sync
whatsapp_number Your WhatsApp number

Session ID

The session_id determines which conversation is shared:

  • Use same ID on desktop and WhatsApp for shared history
  • Use different IDs for separate conversations

How Sync Works Internally

Sending (Desktop → WhatsApp)

When you send from desktop:

  1. Message sent to OpenClaw with --deliver --channel whatsapp flag
  2. OpenClaw processes and generates response
  3. Response delivered to both desktop and WhatsApp

Receiving (WhatsApp → Desktop)

Skippy monitors the session transcript:

  1. TranscriptWatcher checks ~/.openclaw/agents/main/sessions/<session>.jsonl
  2. New messages from WhatsApp detected
  3. Displayed in chat with 📱 prefix
  4. AI response (if any) appears normally

Transcript Location

~/.openclaw/agents/main/sessions/skippy-desktop.jsonl

Each line is a JSON entry with message content, role, timestamps.

Use Cases

Mobile Access

  • Chat with Skippy from anywhere via phone
  • Get responses even when desktop is locked
  • Perfect for quick questions on the go

Hands-Free

  • Use WhatsApp voice messages (not directly supported, but works via WhatsApp's transcription)
  • Receive spoken notifications on phone

Multi-Device

  • Start conversation on desktop
  • Continue on phone
  • Return to desktop with full history

Troubleshooting

Messages Not Syncing to WhatsApp

  1. Check sync enabled: 

    { "sync_whatsapp": true }

  2. Check WhatsApp channel: 

    openclaw channels

  3. Verify number format:

  4. Include country code
  5. Format: +1234567890

WhatsApp Messages Not Appearing

  1. Check transcript watcher:

  2. Look in debug.log for "TranscriptWatcher" entries

  3. Verify session ID:

  4. Both channels must use same session

  5. Check file path: 

    Get-Content "$env:USERPROFILE\.openclaw\agents\main\sessions\skippy-desktop.jsonl" -Tail 5

Duplicate Messages

If seeing messages twice:

  1. Normal behavior for your own messages
  2. Check if both streaming and CLI are active
  3. Restart Skippy to reset state

Privacy Considerations

Shared Session

Messages from all channels (desktop, WhatsApp) are stored in the same session transcript.

End-to-End Encryption

WhatsApp maintains its E2E encryption. Messages to Skippy go through OpenClaw's WhatsApp bridge.

Disabling Sync

Temporarily

  • Uncheck 📱 Sync to WhatsApp in tray menu
  • Messages stay on desktop only

Permanently

{
    "sync_whatsapp": false
}

Best Practices

Use for Quick Queries

WhatsApp is great for simple questions. Use desktop for: - Image analysis - Long conversations - Code-related tasks

Check Both Channels

If a response seems missing, check the other channel - network delays can cause asymmetric delivery.

Session Management

Use /session new on WhatsApp to start fresh if the shared context gets confusing.