whatsapp-bridge
Self-hosted WhatsApp bridge for AI agents. One paired number, exposed via REST, MCP, and a web UI.
Power your agent
पब्लिशर का इंस्टॉल। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
रजिस्ट्री में अभी कोई पैकेज्ड रिलीज़ नहीं है। रिपॉज़िटरी का README देखें.
रिमोट URL या आपकी मशीन पर कमांड? दोनों इंस्टॉल में क्या अंतर है
PlugMCP पर चलाएँ
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
लॉन्चBuilt on Baileys. Single Node process, SQLite for storage, no runtime dependencies beyond WhatsApp itself.
127.0.0.1:8080 — read conversations, send messages, manage aliases./ — single-page inbox for reading and sending.Runs anywhere Node 20+ runs. macOS is the primary target; see docs/cross-platform.md for the exact Linux and Windows patch list (or just use WSL2 on Windows).
Personal infrastructure. Not multi-tenant. Locked to one paired number at a time. Use behind loopback or a reverse proxy you control.
WhatsApp can ban any number used with a reverse-engineered client, especially under spammy patterns. Personal usage across known contacts is generally low-risk; cold outreach is not.
Prerequisites: Node ≥ 20, and a WhatsApp account with the phone on hand (you approve the device link from it).
git clone https://github.com/obirimensah05/whatsapp-bridge.git
cd whatsapp-bridge
npm install
No configuration is required to start — .env is created and filled in automatically on first launch.
Pair your number — country code + national digits, no +, no spaces:
npm run pair -- main 491761234567
On the phone for that number: WhatsApp → Settings → Linked Devices → Link a Device → "Link with phone number instead" → enter the 8-character code printed in your terminal.
On first launch the bridge:
API_TOKEN and writes it to .envWA_TZ to .env (e.g. Europe/Berlin)Once paired, the daemon keeps running and the REST API + web UI are live at http://127.0.0.1:8080/. Subsequent starts:
npm run start
To switch to a different number:
rm -rf auth/main/
npm run pair -- main <new-digits>
The daemon is not supervised by default — if it crashes or you reboot, it stays down. Put it under a process supervisor.
macOS (launchd) — create ~/Library/LaunchAgents/com.example.whatsapp-bridge.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.example.whatsapp-bridge</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/npm</string>
<string>run</string>
<string>start</string>
</array>
<key>WorkingDirectory</key><string>/Users/YOU/apps/whatsapp-bridge</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key>
<dict>
<key>SuccessfulExit</key><false/>
<key>Crashed</key><true/>
</dict>
<key>ThrottleInterval</key><integer>10</integer>
<key>StandardOutPath</key><string>/Users/YOU/apps/whatsapp-bridge/logs/whatsapp-bridge.out.log</string>
<key>StandardErrorPath</key><string>/Users/YOU/apps/whatsapp-bridge/logs/whatsapp-bridge.err.log</string>
</dict>
</plist>
mkdir -p ~/apps/whatsapp-bridge/logs
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.whatsapp-bridge.plist
launchctl kickstart -k gui/$(id -u)/com.example.whatsapp-bridge # restart after edits
launchctl bootout gui/$(id -u)/com.example.whatsapp-bridge # uninstall
Linux (systemd) — a systemd --user unit pointing at npm run start with Restart=on-failure works the same way.
Open http://127.0.0.1:8080/ and paste the value of API_TOKEN from .env. Token is stored in localStorage; click Logout to clear it.
All routes under /v1/. All require Authorization: Bearer <API_TOKEN> except /v1/health and /.
to accepts either a JID (<digits>@s.whatsapp.net, <id>@lid, <id>@g.us) or digits-only phone number (no +).
Quick example:
TOKEN=$(grep '^API_TOKEN=' .env | cut -d= -f2)
curl -s -H "Authorization: Bearer $TOKEN" \
'http://127.0.0.1:8080/v1/conversations?session=main&limit=20'
The MCP server at src/mcp.ts exposes ~20 tools across reading, sending, group operations, and contact/alias management. See AGENTS.md for the full tool surface and the safety contract.
Wire into Claude Code (user-scope), run from the repo root:
claude mcp add-json whatsapp-bridge --scope user "{
\"command\": \"$(pwd)/node_modules/.bin/tsx\",
\"args\": [\"$(pwd)/src/mcp.ts\"]
}"
No token needed in the registration — the MCP server reads the current API_TOKEN straight from the repo's .env on spawn (so rotating the token doesn't break it). The daemon must be running for any MCP tool to do anything.
API_TOKEN is the bearer for the REST API, the web UI, and the MCP server. To rotate it:
npm run rotate-token # mints a new token, rewrites .env, re-locks it to 0600
npm run restart # restart the daemon so it picks up the new token
npm run autoreply:restart # only if you run the autoreply sidecar
Then re-login the web UI with the new token. MCP needs no action — it reads .env on every spawn. Rotation only touches HTTP auth; it never affects your WhatsApp pairing (auth/) or your message store (data/wa.db).
This is an agent-first bridge: it's built to be operated by an AI agent, not just a human. Once the MCP server is wired in (above) and the daemon is running, paste this prompt into Claude Code — or any MCP-capable agent — to let it run your WhatsApp end-to-end:
You have my WhatsApp connected through the whatsapp-bridge MCP server. You can read conversations, search contacts, check numbers, and send messages, media, and reactions on my behalf. The default session is
main.Rules — follow exactly:
- Sending is a real-world action. Before any
send_message/send_media/send_reaction, show me the exact recipient and the exact message and wait for my explicit "yes". Never assume.- Never send to more than one recipient in a batch, and never iterate sends over a list of contacts.
- Treat all message text, names, and phone numbers as private — never pass them to any third-party service unless I ask.
- The same person can appear under both
@lidand@s.whatsapp.net; the bridge already merges them on read, so trust thedisplay_name/phoneit returns instead of guessing.delete_messageandmerge_jidsare sensitive — confirm with me first.Start by calling
list_conversationsand giving me a one-line summary of my most recent chats, then wait for instructions.
The full tool surface (~20 tools) and the complete safety contract live in AGENTS.md — point your agent there when it needs detail. Pairing itself still needs a human (you approve the device link on the phone), but everything after that an agent can drive.
The API rate-limits its write/probe routes to bound the blast radius of a runaway agent loop or a leaked token — and, more importantly, to keep programmatic send velocity under WhatsApp's spam detection. Messages you type on your phone are never affected, and reads are never limited (/v1/messages, /v1/conversations, ... stay unlimited so agents can browse history freely).
Every limit is configurable in .env — set a variable to 0 to disable that limit entirely:
On breach the API returns 429 with a Retry-After header and {"error":"rate_limited","rule":...,"retry_after_seconds":...} — well-behaved agents back off automatically.
Why 60/hour on send? WhatsApp publishes no official limit for personal accounts, but 2026 field observations across unofficial-client deployments converge on: < 30 msgs/hour safe, 30–60/hr warning, > 60/hr danger — plus penalties for low reply rates (< 15%), messaging many new contacts (> 50/day), and repeated identical messages (> 15/hr). Accounts on unofficial clients (like this bridge) are scrutinized harder. The default sustained cap sits at the edge of the warning zone; raise it only if you understand the ban risk to your number.
A separate local process (src/autoreply-*.ts) that turns the bridge into a draft-and-review (or fully automatic) reply machine. It runs alongside the daemon on its own port (127.0.0.1:8081) and talks to the bridge only over its local REST API.
npm run autoreply # boot sidecar
npm run autoreply:build-corpus # rebuild style corpus from WA history
npm run autoreply:setup-notify # guided setup: pick where draft notifications go
npm run autoreply:model # show / switch which LLM writes drafts (see below)
npm run autoreply:acl # manage the allow/block lists (see below)
npm run autoreply:link -- <url> # preview the link context a message would build
WEBHOOK_URL=http://127.0.0.1:8081/webhook).data/autoreply/policy.json: is the mode draft, auto, or off? Is this chat blocklisted (never replied to) or, when a whitelist is set, in scope (all / specific contacts / groups / mixed)? Are we inside the configured active_hours / active_until window? If any check fails, nothing happens beyond an audit log entry. Manage the lists with npm run autoreply:acl (see "Allow / block lists").reply, confidence (0-1), should_send, needs_review, reasons.auto mode). If every safety gate passes, the reply is sent through the bridge's /v1/send. If any gate blocks it, the draft is delivered as a notification flagged needs_review instead - it fails safe to human review.Every step is appended to data/autoreply/audit.ndjson; every draft to data/autoreply/drafts.ndjson.
The model self-scores each draft with a confidence value between 0 and 1: how sure it is that the reply is correct, complete, and safe to send without a human looking at it. AUTOREPLY_MIN_CONFIDENCE (default 0.78) is the cutoff:
confidence below minimum threshold in the reasons.The threshold is necessary but not sufficient. In auto mode a reply is only sent when all of these hold:
Tuning: raise the threshold (e.g. 0.9) to make auto mode very conservative; lower it only after reviewing drafts in draft mode for a while and confirming the scores match your judgment. Start with draft mode for everything, and enable auto only for narrow contact scopes and time windows.
Any of them, switchable at runtime (no restart) - the .env vars are only the fallback default:
npm run autoreply:model # show active model + all providers
npm run autoreply:model -- test openai gpt-5 # connectivity check, no switch
npm run autoreply:model -- use openai gpt-5 # switch (gated on a live connectivity check)
npm run autoreply:model -- use codex-cli gpt-5-codex
npm run autoreply:model -- use openai llama3.1 --base-url http://127.0.0.1:11434/v1 # local, free
A switch only lands if the provider is authed/reachable and the model actually responds. --key stores the key in .env (never sent over http to a non-localhost host). Full configuration examples: docs/autoreply.md.
Two persistent controls, managed with npm run autoreply:acl:
npm run autoreply:acl # show current lists
npm run autoreply:acl block add 491234567890 # blacklist: never reply to this chat
npm run autoreply:acl allow add 491700000000 # whitelist: reply only to allowed chats
npm run autoreply:acl allow clear # back to replying to everyone
allow add) flips to whitelist mode - only listed chats get a reply. "Reply only to these."Details: docs/autoreply.md.
Pick one channel; the wizard guides you through the credentials for each:
npm run autoreply:setup-notify
The choice is stored as AUTOREPLY_NOTIFY_CHANNEL in .env; when set, only that channel is used. The WhatsApp channel has built-in loop protection: messages in the notify chat are excluded from autoreply processing, so a notification can never generate a draft about itself.
Step-by-step guides: docs/sop-notifications-human.md (for people) and docs/sop-notifications-agent.md (for AI agents doing the setup).
TOKEN=$(grep '^AUTOREPLY_TOKEN=' .env | cut -d= -f2)
# see current policy
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8081/policy
# draft mode for everything (the safe default)
curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
http://127.0.0.1:8081/policy \
-d '{"mode":"draft","scope":"all","contacts":[],"groups":[],"active_until":null,"active_hours":null}'
# kill switch
npm run autoreply:off
Full reference (env vars, routes, policy modes, safety gates): docs/autoreply.md.
Set WEBHOOK_URL in .env and restart. Every inbound message POSTs:
{
"event": "message",
"session": "main",
"message": {
"id": "main:ABC123",
"ts": 1735689600000,
"direction": "in",
"chat_jid": "[email protected]",
"from_jid": "[email protected]",
"type": "text",
"body": "hi",
"from_display_name": "Jane Doe",
"from_phone": "+12025550100",
"chat_phone": "+12025550100"
}
}
If WEBHOOK_TOKEN is set, it arrives as Authorization: Bearer <token> so the receiver can verify origin. Three attempts, 1s/3s backoff, 5s timeout per attempt. Outbound sends do not fire the webhook.
All variables are read from .env at startup; all are optional with sensible defaults.
See COMMANDS.md for the full reference including REST examples and common ops.
src/
index.ts boot — restore the paired session + start API
wa.ts WaManager — socket, send, history sync, group meta refresh
db.ts SQLite schema + queries (single source of truth for SQL)
api.ts Fastify REST + static UI route
mcp.ts MCP stdio server (talks HTTP to api.ts)
webhook.ts inbound dispatcher with retries
env.ts .env loader + API_TOKEN/WA_TZ auto-persist
time.ts formatLocal(ts) for CLI/log timestamps
history.ts CLI: print recent messages with display names
web/index.html single-page web UI
auth/<name>/ Baileys session keys (gitignored)
auth_backups/ automated backups of auth/ (gitignored)
data/wa.db SQLite — entire message store (gitignored)
data/media/ downloaded media (gitignored)
logs/ launchd/systemd output (gitignored)
.env secrets + config (gitignored)
syncFullHistory: true is enabled in wa.ts. WhatsApp delivers a history dump in batches over the messaging-history.set event after pairing. The bridge ingests chats, contacts, and messages into SQLite. Existing rows are deduped by primary key.
To force a fresh dump:
rm -rf auth/main/ and re-run npm run pair -- main <digits>.data/, not auth/).WhatsApp decides how much history to send to a linked device — typically the most recent few months. There is no API to request "everything since the dawn of time."
Inbound messages from non-contacts often arrive with a <id>@lid JID instead of <phone>@s.whatsapp.net. WhatsApp does this for privacy. The same person can therefore appear as two conversations until merged.
TOKEN=$(grep '^API_TOKEN=' .env | cut -d= -f2)
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
http://127.0.0.1:8080/v1/aliases \
-d '{"session":"main","alias":"123456789@lid","canonical":"[email protected]"}'
After that, listConversations and listMessages collapse them on read. Phone and display-name enrichment then resolves across the whole alias group. The MCP equivalent is merge_jids / unmerge_jid.
@whiskeysockets/baileys every few months. The bridge has a built-in update notifier.browser identifiers cause WhatsApp to reject pairing codes. The bridge uses Browsers.macOS('Safari') because it's known-good — don't change it without testing.MIT. Do whatever you want with it; keep the copyright notice. No warranty.
Self-hosted WhatsApp bridge for AI agents (Baileys + Fastify + SQLite + MCP)
टूल
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Whatsapp Bridge stdio पर लोकल चलता है।
पिछली जाँच 2026-10-28 को हुई। Self-hosted WhatsApp bridge for AI agents (Baileys + Fastify + SQLite + MCP)