whatsapp-ultimate

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:

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