# Whatsapp Ultimate > Use when working with the most comprehensive WhatsApp skill for AI agents. Full messaging (text, media, polls, stickers, voice), reactions, replies, edits, unsend, complete group management, AND persistent searchable message history with SQLite + FTS5. Native Baileys integration - no external services required. - Skill: `tomevault-io/whatsapp-ultimate` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/whatsapp-ultimate` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/whatsapp-ultimate/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/whatsapp-ultimate --- # WhatsApp Ultimate **Everything you can do in WhatsApp, your AI agent can do too.** This skill documents all WhatsApp capabilities available through OpenClaw's native channel integration. No external Docker services, no CLI wrappers — just direct WhatsApp Web protocol via Baileys. --- ## Prerequisites - OpenClaw with WhatsApp channel configured - WhatsApp account linked via QR code (`openclaw whatsapp login`) --- ## Capabilities Overview | Category | Features | |----------|----------| | **Messaging** | Text, media, polls, stickers, voice notes, GIFs | | **Interactions** | Reactions, replies/quotes, edit, unsend | | **Groups** | Create, rename, icon, description, participants, admin, invite links | | **History** | Persistent SQLite storage, FTS5 full-text search, import historical exports | **Total: 22 distinct actions + searchable history** --- ## Messaging ### Send Text ``` message action=send channel=whatsapp to="+34612345678" message="Hello!" ``` ### Send Media (Image/Video/Document) ``` message action=send channel=whatsapp to="+34612345678" message="Check this out" filePath=/path/to/image.jpg ``` Supported: JPG, PNG, GIF, MP4, PDF, DOC, etc. ### Send Poll ``` message action=poll channel=whatsapp to="+34612345678" pollQuestion="What time?" pollOption=["3pm", "4pm", "5pm"] ``` ### Send Sticker ``` message action=sticker channel=whatsapp to="+34612345678" filePath=/path/to/sticker.webp ``` Must be WebP format, ideally 512x512. ### Send Voice Note ``` message action=send channel=whatsapp to="+34612345678" filePath=/path/to/audio.ogg asVoice=true ``` **Critical:** Use OGG/Opus format for WhatsApp voice notes. MP3 may not play correctly. ### Send GIF ``` message action=send channel=whatsapp to="+34612345678" filePath=/path/to/animation.mp4 gifPlayback=true ``` Convert GIF to MP4 first (WhatsApp requires this): ```bash ffmpeg -i input.gif -movflags faststart -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" output.mp4 -y ``` --- ## Interactions ### Add Reaction ``` message action=react channel=whatsapp chatJid="34612345678@s.whatsapp.net" messageId="ABC123" emoji="🚀" ``` ### Remove Reaction ``` message action=react channel=whatsapp chatJid="34612345678@s.whatsapp.net" messageId="ABC123" remove=true ``` ### Reply/Quote Message ``` message action=reply channel=whatsapp to="34612345678@s.whatsapp.net" replyTo="QUOTED_MSG_ID" message="Replying to this!" ``` ### Edit Message (Own Messages Only) ``` message action=edit channel=whatsapp chatJid="34612345678@s.whatsapp.net" messageId="ABC123" message="Updated text" ``` ### Unsend/Delete Message ``` message action=unsend channel=whatsapp chatJid="34612345678@s.whatsapp.net" messageId="ABC123" ``` --- ## Group Management ### Create Group ``` message action=group-create channel=whatsapp name="Project Team" participants=["+34612345678", "+34687654321"] ``` ### Rename Group ``` message action=renameGroup channel=whatsapp groupId="123456789@g.us" name="New Name" ``` ### Set Group Icon ``` message action=setGroupIcon channel=whatsapp groupId="123456789@g.us" filePath=/path/to/icon.jpg ``` ### Set Group Description ``` message action=setGroupDescription channel=whatsapp groupJid="123456789@g.us" description="Team chat for Q1 project" ``` ### Add Participant ``` message action=addParticipant channel=whatsapp groupId="123456789@g.us" participant="+34612345678" ``` ### Remove Participant ``` message action=removeParticipant channel=whatsapp groupId="123456789@g.us" participant="+34612345678" ``` ### Promote to Admin ``` message action=promoteParticipant channel=whatsapp groupJid="123456789@g.us" participants=["+34612345678"] ``` ### Demote from Admin ``` message action=demoteParticipant channel=whatsapp groupJid="123456789@g.us" participants=["+34612345678"] ``` ### Leave Group ``` message action=leaveGroup channel=whatsapp groupId="123456789@g.us" ``` ### Get Invite Link ``` message action=getInviteCode channel=whatsapp groupJid="123456789@g.us" ``` Returns: `https://chat.whatsapp.com/XXXXX` ### Revoke Invite Link ``` message action=revokeInviteCode channel=whatsapp groupJid="123456789@g.us" ``` ### Get Group Info ``` message action=getGroupInfo channel=whatsapp groupJid="123456789@g.us" ``` Returns: name, description, participants, admins, creation date. --- ## Access Control ### DM Policy Control who can DM your agent in `openclaw.json`: ```json { "channels": { "whatsapp": { "dmPolicy": "allowlist", "allowFrom": ["+34612345678", "+14155551234"], "triggerPrefix": "Jarvis" } } } ``` | Policy | Behavior | |--------|----------| | `"open"` | Anyone can DM | | `"allowlist"` | Only numbers in `allowFrom` can DM | | `"pairing"` | Unknown senders get pairing code prompt | | `"disabled"` | No DMs accepted | ### Group Policy ```json { "channels": { "whatsapp": { "groupPolicy": "open", "groupAllowFrom": ["+34612345678", "+14155551234"] } } } ``` | Policy | Behavior | |--------|----------| | `"open"` | Responds to mentions in any group | | `"allowlist"` | Only from senders in `groupAllowFrom` | | `"disabled"` | Ignores all group messages | ### Self-Chat Mode ```json { "channels": { "whatsapp": { "selfChatMode": true } } } ``` Allows messaging yourself (your "Note to Self" chat) to interact with the agent. ### Trigger Prefix ```json { "channels": { "whatsapp": { "triggerPrefix": "Jarvis" } } } ``` Messages must start with this prefix to trigger the agent. Works in: - Self-chat - Allowed DMs - Any DM where you (the owner) message with the prefix --- ## JID Formats WhatsApp uses JIDs (Jabber IDs) internally: | Type | Format | Example | |------|--------|---------| | Individual | `@s.whatsapp.net` | `34612345678@s.whatsapp.net` | | Group | `@g.us` | `123456789012345678@g.us` | When using `to=` with phone numbers, OpenClaw auto-converts to JID format. --- ## Tips ### Voice Notes Always use OGG/Opus format: ```bash ffmpeg -i input.wav -c:a libopus -b:a 64k output.ogg ``` ### Stickers Convert images to WebP stickers: ```bash ffmpeg -i input.png -vf "scale=512:512:force_original_aspect_ratio=decrease,pad=512:512:(ow-iw)/2:(oh-ih)/2:color=0x00000000" output.webp ``` ### Rate Limits WhatsApp has anti-spam measures. Avoid: - Bulk messaging to many contacts - Rapid-fire messages - Messages to contacts who haven't messaged you first ### Message IDs To react/edit/unsend, you need the message ID. Incoming messages include this in the event payload. For your own sent messages, the send response includes the ID. --- ## Comparison with Other Skills | Feature | whatsapp-ultimate | wacli | whatsapp-automation | gif-whatsapp | |---------|-------------------|-------|---------------------|--------------| | Native integration | ✅ | ❌ (CLI) | ❌ (Docker) | N/A | | Send text | ✅ | ✅ | ❌ | ❌ | | Send media | ✅ | ✅ | ❌ | ❌ | | Polls | ✅ | ❌ | ❌ | ❌ | | Stickers | ✅ | ❌ | ❌ | ❌ | | Voice notes | ✅ | ❌ | ❌ | ❌ | | GIFs | ✅ | ❌ | ❌ | ✅ | | Reactions | ✅ | ❌ | ❌ | ❌ | | Reply/Quote | ✅ | ❌ | ❌ | ❌ | | Edit | ✅ | ❌ | ❌ | ❌ | | Unsend | ✅ | ❌ | ❌ | ❌ | | Group create | ✅ | ❌ | ❌ | ❌ | | Group management | ✅ (full) | ❌ | ❌ | ❌ | | Receive messages | ✅ | ✅ | ✅ | ❌ | | Two-way chat | ✅ | ❌ | ❌ | ❌ | | External deps | None | Go binary | Docker + WAHA | ffmpeg | --- ## Message History & Search (v1.2.0+) OpenClaw now stores **all WhatsApp messages** in a local SQLite database with full-text search (FTS5). Never lose a conversation again. ### How It Works ``` Live Messages (Baileys) ──┐ ├──→ SQLite + FTS5 ──→ whatsapp_history tool WhatsApp Exports (.txt) ──┘ ``` - **Live capture:** Every new message automatically saved - **Historical import:** Bulk import from WhatsApp chat exports - **Full-text search:** Find any message by content, sender, or chat ### Searching History Use the `whatsapp_history` tool (available to your agent automatically): ``` # Search by keyword whatsapp_history action=search query="meeting tomorrow" # Filter by chat whatsapp_history action=search chat="Family Group" limit=50 # Find what you said whatsapp_history action=search fromMe=true query="I promised" # Filter by sender whatsapp_history action=search sender="John" limit=20 # Date range whatsapp_history action=search since="2026-01-01" until="2026-02-01" # Database stats whatsapp_history action=stats ``` ### Importing Historical Messages WhatsApp doesn't expose infinite history via API. To get older messages: 1. **Export from phone:** Settings → Chats → Chat history → Export chat → Without media 2. **Save the .txt files** somewhere accessible 3. **Import:** ``` whatsapp_history action=import path="/path/to/exports" ``` Or import a single chat: ``` whatsapp_history action=import path="/path/to/chat.txt" chatName="Family Group" ``` ### Database Location ``` ~/.openclaw/data/whatsapp-history.db ``` SQLite file with WAL mode for concurrent access. ### Use Cases - *"What did I tell Sarah about the meeting?"* - *"Find all messages mentioning 'deadline'"* - *"Show my recent messages to the work group"* - *"When did John mention the quarterly report?"* The agent can now answer these questions by searching your complete WhatsApp history. --- ## Troubleshooting ### Messages from family/friends not reaching agent **Symptom:** You added someone to `groupAllowFrom` but their DMs don't work. **Fix:** Add them to `allowFrom` too. `groupAllowFrom` only controls group message access, not DMs. ```json { "allowFrom": ["+34612345678", "+14155551234"], "groupAllowFrom": ["+34612345678", "+14155551234"] } ``` ### Can't tell who sent which message in a DM **Symptom:** All messages in a DM conversation show the same phone number. **Cause:** Prior to OpenClaw 2026.2.1, DM messages showed the *chat ID* (the other person's number) instead of the *actual sender*. **Fix:** Update to latest OpenClaw. The agent now correctly distinguishes between messages you send and messages the other person sends in the same conversation. ### Voice notes won't play on WhatsApp **Symptom:** Audio file sends but shows as unplayable. **Fix:** Use OGG/Opus format, not MP3: ```bash ffmpeg -i input.mp3 -c:a libopus -b:a 64k output.ogg ``` Then send with `asVoice=true`. --- ## Architecture ``` Your Agent ↓ OpenClaw message tool ↓ WhatsApp Channel Plugin ↓ Baileys (WhatsApp Web Protocol) ↓ WhatsApp Servers ``` No external services. No Docker. No CLI tools. Direct protocol integration. --- ## License MIT — Part of OpenClaw --- ## Links - OpenClaw: https://github.com/openclaw/openclaw - Baileys: https://github.com/WhiskeySockets/Baileys - ClawHub: https://clawhub.com --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/kbarbel640-del) — claim your Tome and manage your conversions.