WhatsApp Ultimate

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](https://clawhub.com/globalcaos/jarvis-voice) for WhatsApp voice notes and [ai-humor-ultimate](https://clawhub.com/globalcaos/ai-humor-ultimate) for personality. Both part of a 13-skill cognitive architecture.

👉 [Clone it. Fork it. Break it. Make it yours.](https://github.com/globalcaos/clawdbot-moltbot-openclaw)

---

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:

1. apply-history-fix.sh — Captures self-chat messages that Baileys misses. Modifies monitor.ts.

2. 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

Review first, then run:
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:

1. Which model answered (was it a fallback?)

2. 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