| name | whatsapp-ultimate |
| version | 3.4.0 |
| description | WhatsApp skill with a 3-rule security gate. Your agent speaks only when spoken to — in the right chat, by the right person. |
| metadata | {"openclaw":{"emoji":"💬","os":["linux","darwin"],"requires":{"bins":["npx","tsx","sed","python3"],"channels":["whatsapp"]},"patches":{"description":"Two optional bash scripts patch OpenClaw source files to add (1) self-chat history capture in monitor.ts and (2) model/auth prefix template variables in response-prefix-template.ts, types.ts, reply-prefix.ts, and agent-runner-execution.ts. Both scripts are idempotent (safe to run multiple times) and skip if already applied. Review the scripts before running.","files":["scripts/apply-history-fix.sh","scripts/apply-model-prefix.sh"],"modifies":["src/web/inbound/monitor.ts","src/auto-reply/reply/response-prefix-template.ts","src/auto-reply/types.ts","src/channels/reply-prefix.ts","src/auto-reply/reply/agent-runner-execution.ts"],"mechanism":"sed + python3 string replacement with anchor-point matching","reversible":"git checkout on modified files restores originals"},"notes":{"security":"PATCHES: Two optional install scripts modify OpenClaw source files using sed and python3 to add history capture and model prefix features. Both are idempotent and skip if already applied. Review scripts/apply-history-fix.sh and scripts/apply-model-prefix.sh before running. ADMIN SCRIPTS: wa-fetch-contacts.ts and wa-create-group.ts connect to WhatsApp via Baileys using existing OpenClaw credentials in ~/.openclaw/credentials/whatsapp/. No new credentials are requested. No external network calls beyond WhatsApp's own WebSocket connection. All operations are local."}}} |
WhatsApp Ultimate
Your agent won't flirt with your boss in the company group.
It won't offer unsolicited life advice to your mother-in-law. It won't settle a family debate about paella with a 400-word essay nobody asked for. It won't reply "Actually..." to your partner's story at 2 AM.
Because WhatsApp Ultimate has a 3-rule security gate: right person + right chat + right prefix = response. Everything else = absolute silence. Not "maybe silence." Not "I'll just help a little." Stone-cold, disciplined, beautiful silence.
That's the gate. Here's the engine:
- 🤖 Model ID on every reply —
claude-opus-4-6|sub stamped on each message, so nobody mistakes the bot for a human
- Full message history capture — every conversation stored and searchable. Context that doesn't evaporate.
- Contact sync + group management — your agent knows who's who without hand-holding
- Thinking heartbeat — typing indicators while processing, so users know it's alive
- Direct Baileys API — no middleware bloat. Fast. Light. Reliable.
Three rules. Zero awkward moments. Because we're that kind of obsessive.
The Full Stack
Pair with jarvis-voice for WhatsApp voice notes and ai-humor-ultimate for personality. Both part of a 13-skill cognitive architecture.
👉 Clone it. Fork it. Break it. Make it yours.
Features
Messaging & Monitoring
- Model ID Prefix: Every bot message shows which model and auth mode is active:
🤖(claude-opus-4-6|sub) or 🤖(gpt-4o|api). Instantly know what's running.
- Complete Message History: Captures ALL messages — including self-chat inbound messages that Baileys misses
- Self-Chat Mode: Full bidirectional logging in your own chat (command channel)
- Security Gating: 3-rule allowlist — authorized users, authorized chats, trigger prefix
- Full History Sync: Enable
syncFullHistory: true to backfill messages on reconnect
Administration & Group Management
- Contact Sync: Extract all contacts from all WhatsApp groups with phone numbers, admin status, and LID resolution
- Group Creation: Create groups programmatically with participant lists
- Group Management: Rename, update descriptions, add/remove/promote/demote participants
- Direct Baileys Access: Bypasses the gateway — works even if the listener is down
Setup
Install
clawhub install whatsapp-ultimate
⚠️ Patches (Optional — Read Before Running)
This skill includes two optional bash scripts that patch OpenClaw source files. The base skill (security gating, admin tools, contact sync) works without them. The patches add:
apply-history-fix.sh — Captures self-chat messages that Baileys misses. Modifies monitor.ts.apply-model-prefix.sh — Adds model/auth info to every reply. Modifies response-prefix-template.ts, types.ts, reply-prefix.ts, agent-runner-execution.ts.
Before running:
- Read each script — they're short and commented
git commit your OpenClaw repo first (so you can git checkout to revert)- Both scripts are idempotent (safe to run multiple times)
- Both skip automatically if already applied
bash ~/.openclaw/workspace/skills/whatsapp-ultimate/scripts/apply-history-fix.sh
bash ~/.openclaw/workspace/skills/whatsapp-ultimate/scripts/apply-model-prefix.sh
What they touch:
| Script | Files Modified | What Changes |
|---|
| apply-history-fix.sh | src/web/inbound/monitor.ts | Adds insertHistoryMessage() call to store all inbound messages |
| apply-model-prefix.sh | 4 files in src/ | Adds {authMode} and {authProfile} template variables |
To revert: git checkout -- src/ from your OpenClaw repo root.
Config (openclaw.json)
{
"channels": {
"whatsapp": {
"selfChatMode": true,
"syncFullHistory": true,
"responsePrefix": "🤖({model}|{authMode})",
"dmPolicy": "allowlist",
"allowFrom": ["+your_number"],
"triggerPrefix": "jarvis"
}
}
}
Model ID Prefix
The responsePrefix supports template variables:
| Variable | Example | Description |
|---|
{model} | claude-opus-4-6 | Short model name |
{authMode} | sub / api | Auth mode: sub = subscription/OAuth, api = API key |
{provider} | anthropic | Provider name |
{auth} | sub | Alias for {authMode} |
{authProfile} | anthropic:oauth | Full auth profile ID |
{think} | low | Current thinking level |
Prefix examples:
🤖(claude-opus-4-6|sub) — Opus on subscription🤖(claude-opus-4-6|api) — Opus on API key (costs money!)🤖(gpt-4o|api) — GPT-4o fallback🤖(llama3.2:1b|api) — Local Ollama model
This lets you immediately identify:
- Which model answered (was it a fallback?)
- Whether you're burning subscription or API credits
Self-Chat History Fix
Problem: Baileys doesn't emit messages.upsert events for messages you send from your phone to your own self-chat. They never reach the history DB.
Solution: The patch adds insertHistoryMessage() in the inbound monitor — right where messages are processed after access control. Every message the bot sees gets stored. Duplicates are silently ignored.
Additionally: syncFullHistory: true triggers full message backfill on reconnect.
Usage
whatsapp_history(action="search", query="meeting tomorrow")
whatsapp_history(action="search", chat="Oscar", limit=20)
whatsapp_history(action="stats")
Administration Tools
Contact Sync
Extract all contacts from all WhatsApp groups:
npx tsx ~/.openclaw/workspace/skills/whatsapp-ultimate/scripts/wa-fetch-contacts.ts
Output: ~/.openclaw/workspace/bank/whatsapp-contacts-full.json
Contains: all groups with participant counts, all contacts with phone numbers (LID-resolved), group membership per contact, admin status.
Group Creation
npx tsx ~/.openclaw/workspace/skills/whatsapp-ultimate/scripts/wa-create-group.ts "Group Name" "+phone1" "+phone2"
Phone numbers in E.164 format. Creator auto-added as admin. Returns group JID.
Key Baileys Methods
| Method | Description |
|---|
groupFetchAllParticipating() | Get all groups + participants |
groupMetadata(jid) | Get single group details |
groupCreate(name, participants) | Create new group |
groupUpdateSubject(jid, name) | Rename group |
groupUpdateDescription(jid, desc) | Update group description |
groupParticipantsUpdate(jid, participants, action) | Add/remove/promote/demote |
LID Resolution
WhatsApp uses LIDs (Linked IDs) internally. The contact sync script automatically resolves LIDs to phone numbers using mappings in ~/.openclaw/credentials/whatsapp/default/lid-mapping-*_reverse.json.
Changelog
3.4.0
- Fixed: Chat search now resolves LID/JID aliases — searching by chat name finds messages across both
@lid and @s.whatsapp.net JID formats
- Added:
resolveChatJids() cross-references chats, contacts, and messages tables to discover all JID aliases for a given chat filter
- Improved: Search falls back to original LIKE behaviour if no JIDs resolve, so no regressions
3.0.0
- Merged: whatsapp-tools into whatsapp-ultimate — contact sync, group creation, and admin operations now included
- Added: Proper metadata.openclaw block with required bins, channels, and security notes
- Added: Administration Tools section with Baileys API reference and LID resolution docs
2.2.0
- Added: Model + auth mode prefix in every message (
{model}, {authMode} template vars)
- Added: Install script for model prefix patch
- Added: Full template variable documentation
2.1.0
- Fixed: Self-chat inbound messages now captured in history DB
- Added: Install script for history capture patch
- Added:
syncFullHistory config for full backfill
2.0.3
- Initial ClawHub release with security gating and bot prefix
