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 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:

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:

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:

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

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