| name | whatsapp |
| description | Send and read WhatsApp messages via the wacli CLI. Search chats, view history, send text and files to contacts or groups. |
| requires_bridge | whatsapp |
WhatsApp
Use the whatsapp bridge to read and send WhatsApp messages via the wacli CLI.
When to Use
- User asks to send a WhatsApp message
- Reading WhatsApp conversation history
- Searching WhatsApp chats or messages
When NOT to Use
- Telegram messages -> reply normally (Ciana routes automatically)
- iMessage/SMS -> use the
imessage bridge
- Any other messaging platform
Pre-flight: Ensure Sync is Running
Before any WhatsApp operation, check that wacli is connected and syncing:
- Run
wacli-daemon status to check if the sync daemon is running
- If the status is "stopped", start it:
wacli-daemon start
- After starting, wait a few seconds, then verify with
wacli doctor that CONNECTED is true
- Only then proceed with the actual command
This ensures messages are always up-to-date without requiring the user to manually sync.
If wacli doctor shows AUTHENTICATED as false, tell the user they need to re-authenticate with wacli auth on the host (this requires scanning a QR code and cannot be done remotely).
Commands
All commands run via host_execute(bridge="whatsapp", command="...").
Sync Daemon Management
wacli-daemon status # Check if sync is running
wacli-daemon start # Start sync in background (idempotent)
wacli-daemon stop # Stop background sync
List Chats
wacli chats list --limit 20
wacli chats list --limit 20 --query "John"
Search Messages
wacli messages search "query" --limit 20
wacli messages search "query" --limit 20 --chat <jid>
wacli messages search "query" --after 2025-01-01 --before 2025-02-01
Send Text
wacli send text --to "+14155551212" --message "Hello!"
For groups, use JID format:
wacli send text --to "1234567890-123456789@g.us" --message "Hello group!"
Send File
wacli send file --to "+14155551212" --file /path/to/image.jpg --caption "Check this"
Auth & Diagnostics
wacli auth # Interactive QR code authentication (host only)
wacli doctor # Check auth/connection/store status
Contact Resolution
When the user asks to message someone by name (e.g. "send a message to Marco"), never say you don't have the number. Instead:
- Search chats first:
wacli chats list --query "Marco"
- If found, use the JID or phone number from the result to send
- If multiple matches, show the list and ask the user to pick
- Only if no match is found, ask the user for the number
Safety Rules
- Always confirm recipient and message content before sending
- Never send to unknown numbers without explicit user approval
- Rate limit - don't spam
Setup (on host)
- Install wacli:
brew install steipete/tap/wacli
- Install daemon:
ln -sf $(pwd)/scripts/wacli-daemon /opt/homebrew/bin/wacli-daemon
- Authenticate:
wacli auth (scan QR code with WhatsApp on phone)
- Initial sync:
wacli-daemon start
- Add
whatsapp bridge in config.yaml, restart gateway
