whatsapp

name	whatsapp
description	Query WhatsApp chats, messages, contacts, groups. Send, forward, react. Use when the user asks about their WhatsApp messages, wants to search history, send messages, or manage chats.

whatsapp-cli Skill

Query and manage WhatsApp data via the whatsapp CLI.

Prerequisites

• Install CLI: curl -fsSL https://raw.githubusercontent.com/eddmann/whatsapp-cli/main/install.sh | sh
• Authenticate: whatsapp auth login (scan QR code)

Quick Context

Get aggregated WhatsApp data in one call:

whatsapp context                    # Connection status + recent chats with messages
whatsapp context --chats 10         # More recent chats
whatsapp context --messages 20      # More messages per chat

Messages come from a local database. Run whatsapp sync to fetch latest messages if history seems stale.

Commands

Run whatsapp --help or whatsapp <command> --help to discover all options.

Chats & Messages

whatsapp chats [--query NAME] [--groups] [--limit N]
whatsapp messages <JID> [--timeframe today] [--type image] [--limit N]
whatsapp search "keyword" [--chat JID] [--timeframe this_week]

Send, Forward, React

whatsapp send <JID> "message" [--file photo.jpg] [--reply-to MSG_ID]
whatsapp forward <TO_JID> <MSG_ID> --from <SOURCE_JID>
whatsapp react <MSG_ID> "thumbsup" --chat <JID>

Groups

whatsapp groups [JID]               # List or get info
whatsapp groups join <CODE>         # Join via invite
whatsapp groups leave <JID>

Other

whatsapp contacts [--query NAME]
whatsapp alias [JID NAME] [--remove]
whatsapp download <MSG_ID> --chat <JID>
whatsapp export <JID> [--output file.json]
whatsapp sync [--follow]
whatsapp doctor [--connect]

JID Types

Type	Format	Example
Individual	<phone>@s.whatsapp.net	[e-mail]
Group	<id>@g.us	[e-mail]

Use whatsapp chats to look up JIDs.

Timeframe Presets

last_hour, today, yesterday, last_3_days, this_week, last_week, this_month

Message Types

text, image, video, audio, document, sticker

Data Units

Field	Format
timestamp	ISO8601 UTC (e.g., 2025-12-15T10:30:00Z)
jid	WhatsApp JID (see JID Types above)
is_from_me	boolean

Common Patterns

# Find a chat and read messages
whatsapp chats --query "John" | jq -r '.[0].jid'
whatsapp messages [e-mail] --timeframe today

# Search and reply
whatsapp search "meeting" --timeframe this_week
whatsapp send <JID> 'See you there!' --reply-to <MSG_ID>

# Filter with jq
whatsapp messages <JID> | jq '[.[] | select(.is_from_me==false)]'

# Export for analysis
whatsapp export <JID> --output chat.json

Auth Status

whatsapp auth status    # Check if authenticated
whatsapp auth login     # QR code auth
whatsapp auth logout    # Clear session

Exit Codes

• 0 = Success
• 1 = General error (check stderr)