io.github.razvangirgiz/wazap

██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝

WhatsApp for your AI agent. An MCP server that puts your WhatsApp account — chats, messages, media, contacts, groups — behind 34 tools any MCP client can call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.

Built on Baileys, which speaks the WhatsApp multi-device protocol over a WebSocket.

Get started

The npm package is wazap-mcp; the command it installs is wazap.

npx wazap-mcp setup

That is the whole install. It links your account, finds the MCP clients installed on this machine, writes their config, copies the five skills where that client reads them, and tells you what to restart. At a terminal it is one black, centered screen per step: ghosted ASCII logo, step number, then the QR or the question. Piped output stays a log. When you started through npx, setup offers to install wazap globally so Claude Desktop and the background service have a path that does not change. It also offers to brew install whisper-cpp, ffmpeg or Tailscale when a step needs one and it is missing, and to restart Claude Desktop itself once it has connected it.

Or the path your harness prefers

Each local harness registers the server. Grok Bot is a URL you paste. Linking the WhatsApp account is a separate, one-time step: npx wazap-mcp login.

Or have your agent do it. Paste this:

Set up WhatsApp for me: run npx wazap-mcp setup --agent and follow what it prints.

Then ask your agent: "what did I miss on WhatsApp today?"

Below are the steps setup runs for you. Each is still its own command when you want to run it by hand.

npx wazap-mcp login shows a QR code; scan it from Settings → Linked devices → Link a device. No camera handy, or linking over SSH? npx wazap-mcp login --phone +15550100 prints an 8-character code you type under Link with phone number instead. It ends by asking whether the agent may send messages; the answer is no unless you say yes, and npx wazap-mcp config writes on changes it later.

npx wazap-mcp connect claude-code writes the MCP entry for one client. The table under Connect a client has the rest.

npx wazap-mcp on its own is safe to run: it prints where you stand and what to do next, and starts no server. When something is off, npx wazap-mcp status is the first thing to run — it checks Node, the data directory, the lock, the credentials and whether a newer version is out, and prints the fix next to anything broken.

Connect a client

wazap connect <client> writes the entry for you, keeping whatever else is in the file and backing it up once before the first change. --dry-run shows what it would write.

Grok Bot / remote MCP

Grok Bot is an HTTP MCP client. It does not launch wazap over stdio.

1. On the machine that will run wazap, npx wazap-mcp login until the CLI says the account is linked. get_status and link_account are MCP tools; they need HTTP already serving (step 3) and Grok already connected (step 4).
2. Answer writes yes or no at login. Writes stay on when WAZAP_READ_ONLY is unset. A Bearer write token is not writes being enabled. If write tools are missing, you need writes on (wazap config writes on and restart) and a write Bearer on this session. Config alone is not enough on HTTP.
3. Serve HTTP with a read token:

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http

Set WAZAP_WRITE_TOKEN too only if this client should send, and put that value in the header in step 4.

4. In Grok Bot, add an MCP server at http://<host>:<port>/mcp with header Authorization: Bearer <token>. Then call learn, then get_status. connected means the WhatsApp socket is up. This session can send only when write tools are registered (write_tools: true, or send tools appear in the tool list). Then read.

wazap setup asks Remote client (Grok Bot / HTTP MCP)? and prints the same URL and header. Answering yes does not start expose.

Other MCP clients

Cursor and VS Code install from a link:

Both carry the same entry connect writes. Where a custom scheme is stripped before you can click it, VS Code also takes the https form. node scripts/badges.mjs reprints all three.

Any other MCP client works the same way: the command is npx -y wazap-mcp, the transport is stdio. Tell the agent to call learn first — it returns the id formats, the workflows and every error code with what to do about it.

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "wazap-mcp"]
    }
  }
}

[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]

{
  "mcp": {
    "whatsapp": { "type": "local", "command": ["npx", "-y", "wazap-mcp"] }
  }
}

The skills/ folder follows the Agent Skills format, so Codex, Cursor and other skill-aware agents can load the same five skills.

Gemini CLI

gemini extensions install https://github.com/razvangirgiz/wazap

That reads gemini-extension.json at the repo root, so it registers the MCP server and loads GEMINI.md — the five skills below, concatenated, because the Gemini CLI takes one context file per extension rather than a skills directory. wazap connect gemini writes the server alone, without the context.

GEMINI.md is generated: npm run context:build rebuilds it from skills/*/SKILL.md, and a test fails if the two have drifted, so a workflow is only ever edited in its skill.

Claude Desktop, without a terminal

Download wazap-<version>.mcpb from Releases and double-click it. Claude Desktop installs the server, its Node dependencies and the icon, and shows two settings: Read-only, ticked, and Data directory, empty. wazap connect claude-desktop does the same job by editing claude_desktop_config.json. Claude Desktop starts its servers without your shell PATH, so that entry is the absolute path to node when wazap is installed globally, and npx otherwise; wazap setup checks that the entry it wrote is one Claude Desktop can actually launch.

Then ask Claude to link your WhatsApp. It calls link_account with your number, hands back an 8-character code, and you type that code into WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead. No terminal at any point. npx wazap-mcp login does the same job from a shell when you have one.

Untick Read-only to let Claude send. It ships ticked because a bundle that can message people from your number before you have said so is the wrong default, and because the setting cannot be left unanswered: the manifest format has no way to omit an argument, so the box you see is the answer the server gets. link_account is registered either way. Read-only exists to stop Claude messaging people from your number, and relinking your own dead session messages nobody.

Build it yourself with npm run bundle:mcpb, which stages dist/, the manifest, the icon and a fresh production node_modules, then packs them with @anthropic-ai/mcpb.

Keep it running

A wazap started by a client lives as long as that client does. Quit Claude Code and the session is gone until you open it again. Two commands change that. Staying up and being reachable are separate choices.

npx wazap-mcp service install

That writes a launchd agent on macOS (~/Library/LaunchAgents/com.wazap.server.plist) or a systemd user unit on Linux (~/.config/systemd/user/wazap.service), starts it, and waits for /healthz to answer. The unit runs serve --http on 127.0.0.1:8766 with the absolute path of this Node and this install, so it survives a reboot and a logout. Point any client at http://127.0.0.1:8766/mcp, or keep using the stdio entry. A second wazap on the same data directory becomes a bridge onto the session this one holds.

service status prints the pid, the health check and whether the unit still runs the version you have installed. service logs tails it. service restart picks up an upgrade; service uninstall removes the unit and leaves your session and credentials alone. wazap login needs the session to itself, so it stops the service, pairs, and starts it again on its own.

A sleeping Mac is an offline wazap. System Settings → Lock Screen, or Battery → Options, has the switch that keeps it awake on power.

npx wazap-mcp expose

That gives the running service a public https URL, for agents that are not on this machine: a cloud agent, claude.ai, ChatGPT. It uses Tailscale Funnel if tailscale is installed, Cloudflare Tunnel if cloudflared is, opens the tunnel, writes WAZAP_PUBLIC_URL and a fresh WAZAP_OAUTH_PASSWORD into <data-dir>/.env, restarts the service and checks the URL from here. It then prints the MCP URL and the password once.

Give an agent the URL only. It signs in on a consent page on your own host with that password and picks read or read-and-send there; wazap status lists who holds a grant. See Hosted agents (OAuth) for what that page does. npx wazap-mcp expose off takes the tunnel down and keeps the password, so the next expose hands agents the same one.

npx wazap-mcp setup asks all of this once, as its fourth step.

Upgrade

npx wazap-mcp update

One command for what used to be three. It compares this install against the registry, installs the new package when wazap is global, restarts the service so it runs the new code, and copies the new skills into every harness that keeps them. --dry-run prints the plan and touches nothing.

Tools

Seeing, waiting, following up

include_previews: true on get_recent_messages or read_messages attaches a small JPEG of each photo as an image block, newest first, up to 12 per call, and labels each message line with the preview it belongs to, so a catch-up can say "a photo of a receipt" without a download. WhatsApp used to ship such a preview inside every image message and in 2026 almost never does, so when none is there wazap downloads the photo once, shrinks it to 320 px on this machine with pure JavaScript, and keeps the result as a file under previews/ in the data directory, so a restart does not redo it. A video gets one frame, taken by ffmpeg a second in, when ffmpeg is installed. The first call over a day of photos takes a few seconds; the next is instant.

wait_for_messages blocks until something arrives, up to 55 seconds, then returns it with a cursor. Calling it again with that cursor replays whatever landed in between, so an agent can sit in a loop and miss nothing. With addressed_to_me only direct messages, @-mentions of the user and replies to their messages wake it; group chatter does not. The user's own messages and WhatsApp's notices never do.

get_unanswered returns the chats whose last word is the other side's and reads as an ask: a question mark, a request word, or a voice note nobody has heard yet. "Ok, thanks" is not an ask, a link is not a question, and an ask older than two weeks (max_age_hours) was abandoned rather than left waiting. People come first, then the oldest wait, each with the ask quoted and how long they have been waiting; a WhatsApp Business account is marked, since its asks are often automatic replies.

Every message comes back with a non-empty text: media and system messages carry a placeholder such as [image] caption, [voice message · 0:42], [deleted] or [poll] Pizza or pasta?. Timestamps are ISO 8601 with the machine's UTC offset, alongside a human age like 2h ago.

Voice messages

A voice note is the one message an agent cannot read. Switch transcription on and it becomes text: [voice message · 0:42] "sunt la notar, ajung în 20 de minute", with the bare words also in a transcript field. get_recent_messages and search_messages see that text, so a voice note becomes findable by what was said in it.

Pick a provider once, in wazap setup or later:

wazap config transcribe local     # free and private, one 574 MB model on disk
wazap config transcribe openai    # cheap and fast, the audio leaves this machine
wazap config transcribe off

Local, with whisper.cpp

brew install whisper-cpp ffmpeg      # macOS; elsewhere build whisper.cpp, install ffmpeg from your package manager
wazap transcribe download            # fetch and verify the model
wazap transcribe test recording.ogg  # prove it before you trust it

wazap setup and wazap transcribe download offer that brew install themselves when either binary is missing, and go straight on to the model in the same run. --no-brew turns the offer off everywhere.

Models land in <data-dir>/models/ and are checked against a SHA-256 pinned in the source; an interrupted download resumes where it stopped.

turbo is the default because it is the smallest model that still gets Romanian right. medium and below drop diacritics and mangle names, which is worse than no transcript at all: a missing transcript is a question, a wrong name is a wrong answer. large-v3 is the same accuracy for several times the wait.

An API, OpenAI-compatible

wazap config transcribe openai asks for the key without echoing it and stores it in <data-dir>/.env. The default endpoint is OpenAI; Groq works unchanged:

WAZAP_TRANSCRIBE_URL=https://api.groq.com/openai/v1
WAZAP_TRANSCRIBE_MODEL=whisper-large-v3-turbo

With this provider the audio leaves your machine. Every voice note wazap transcribes is uploaded to that endpoint. If that is not acceptable, use local, which uploads nothing.

The key is treated as a secret rather than as a setting:

• It is never accepted as a command-line argument, because an argument lands in your shell history and in ps.
• The prompt echoes nothing, not even asterisks.
• It is stored only in <data-dir>/.env, mode 0600.
• status, status --json, config and get_status show at most api key: set (…abcd).
• A provider's own error message has the key stripped out of it before wazap prints it.
• A plain-http WAZAP_TRANSCRIBE_URL is refused unless it points back at this machine.

Without being asked

With a provider configured, incoming voice notes of up to ten minutes are transcribed in the background as they arrive, one at a time, never holding up a message. The transcript is cached by message id and persisted, so a voice note is transcribed once and not again after a restart. Audio files are left alone, since one can be an hour long; call transcribe_audio(message_id) for those. WAZAP_TRANSCRIBE_AUTO=0 keeps the tool and stops the background work.

Semantic recall

search_messages matches exact words; recall matches what was meant. A paraphrase or another language still hits, and it keeps finding messages too old for search_messages to see — those come back marked index only, which get_message and download_media cannot open. For an exact string — an id, a phone number, a URL — search_messages stays the right tool.

Off by default, and fully local: a llama-server sidecar bound to loopback does the embedding, so nothing leaves the machine. It needs llama.cpp, the pinned model and persisted history (WAZAP_PERSIST_HISTORY, on by default):

brew install llama.cpp      # macOS; elsewhere build llama.cpp and put llama-server on PATH
wazap embed download        # fetch the embedding model, ~318 MB sha256-verified
wazap config recall local   # then restart the service

wazap embed download offers the brew install itself when llama-server is missing. wazap status runs the three checks — recall, llama-server, embed model — and get_status reports the index as off, indexing, ready or degraded.

chat_id, since, until and from narrow a recall exactly like search_messages. Hits rank by similarity scaled by recency, and anything under the similarity floor is dropped rather than listed. The index lives at accounts/<id>/recall/ (dir 0700, files 0600), holds only what persisted history already stores, and tombstones a message out when it is deleted or revoked.

The knobs — WAZAP_RECALL, WAZAP_EMBED_MODEL (embeddinggemma-300m by default, e5-base-multilingual for an older llama.cpp), WAZAP_EMBED_BIN, WAZAP_RECALL_MAX, WAZAP_RECALL_MIN_SIMILARITY — are documented in .env.example.

Skills

wazap ships five Agent Skills that teach an agent the workflows behind the tools, not just the tools:

wazap setup copies them into every client it connects, so there is usually nothing to run. The command behind it, for a harness setup never offered or for a checkout you want to install by hand:

npx wazap-mcp skills install codex     # or claude-code, cursor, opencode, agents

With no harness named it installs into every client it finds on this machine. For Claude Code the other route is the plugin, which carries the server as well:

/plugin marketplace add razvangirgiz/wazap
/plugin install wazap@wazap

Re-running overwrites, so an upgrade is the same command. --dry-run lists what it would copy.

A client with no skills directory is not left out. The server registers each of the five as an MCP prompt of the same name, and sends a short instructions block that names all five and says when each applies, so an agent that never saw the skill files still follows them. That is how Claude Desktop, VS Code and Windsurf get the workflows. A bridged session and a self-hosted HTTP server carry them the same way.

Errors

Every failure is a structured { error, message, fix } rather than a stack trace, so an agent can decide whether to retry, ask the user, or stop.

Data directory

Everything lives in ~/.wazap (override with --data-dir or WAZAP_DATA_DIR), created 0700 with credentials written 0600. A data dir from before several accounts moves into accounts/default/ the first time a wazap command runs.

~/.wazap/
  accounts.json     which accounts exist, and which is default
  accounts/<id>/
    auth/           WhatsApp credentials — treat this like a password
    media/          downloads from download_media
    history/        per-chat message history, so a restart is not amnesia
    recall/         the semantic index, when recall is on
    previews/       one small JPEG per photo or video already previewed
    notes.json      notes on contacts and "handled" marks; never sent anywhere
    store.json      chat-list snapshot
    qr.png          last QR, when login showed one
  models/           whisper.cpp and embedding models, when transcription or recall run locally
  server.lock       pid of the running server
  daemon.json       loopback endpoint a second wazap bridges to
  oauth.json        registered agents and hashed OAuth grants, when OAuth is on
  .env              optional settings, see .env.example
  migration.json    written once when a flat dir moved into accounts/default

Credential writes go to a temp file and are renamed into place, so killing the process mid-write cannot leave you re-linking your phone.

Several accounts

One wazap serve holds every enabled account in the data dir. Each account is its own Baileys socket and its own folder under accounts/<id>/. The first account is default. Add another with wazap account add work --name Work, then wazap login --account work.

--account picks one on login, logout, status, config writes and webhook test. MCP tools take an optional account_id. Call list_accounts first when more than one is linked. A chat only one account knows selects that account. A send to a chat no account knows, with two or more accounts, fails AMBIGUOUS_ACCOUNT instead of falling back to default.

Reads without a chat and without account_id use the default account; the response still carries account_id. link_account needs an account that already exists. Five accounts is advice, not a cap. One phone number is one account.

An account can override the global webhook URL, secret and event list in accounts.json (webhook_url, webhook_secret, webhook_events). wazap webhook test --account work posts with that account's id and name.

Several clients at once

Claude Desktop, Claude Code and Cursor each launch their own wazap. The first one on a data directory owns every enabled account, each on its own socket, and opens an MCP endpoint on 127.0.0.1; every later one bridges to it over that endpoint. There is nothing to configure, and no client can tell the difference. The owner publishes <data-dir>/daemon.json (0600) with its pid, its port and the token a bridge authenticates with.

A bridge serves whatever the owner exposes, so an owner started --read-only makes every client read-only, whatever flags that client was launched with.

When the owner exits, the bridges exit with it, and the next wazap a client starts becomes the new owner.

WAZAP_NO_SHARE=1 opts out: a second wazap on the same directory exits with code 2 naming the pid of the one already running. An explicit --http is a server of its own rather than a bridge, and is refused the same way.

Read-only mode

Writes are opt-in at login (the question defaults to no and stores the answer in <data-dir>/.env). wazap config writes on|off changes it later. wazap config and wazap status print the effective setting and where it came from. If that line says off, write tools are not registered: run wazap config writes on and restart the server.

An unset WAZAP_READ_ONLY and WAZAP_READ_ONLY=0 both register write tools (wazap config then says "writes: on"). WAZAP_READ_ONLY=1 or wazap serve --read-only does not register them at all. The agent never sees them, so it cannot message anyone from your number even by mistake.

Writes are also rate limited to WAZAP_RATE_LIMIT per minute (default 20, 0 disables). Sending faster than a human is how accounts get banned.

HTTP mode

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http --host 0.0.0.0 --port 8766

Streamable HTTP at /mcp, with a health check at /healthz. That check answers { ok, status, since }. It turns 503 once the socket has been anything but connected for two minutes, so a tunnel or a monitor sees a real outage rather than a reconnect in progress. Two bearer tokens: the read token gets the read tools, the write token can unlock the write tools. A leaked read token can never message anyone. A write token is not the same as writes being enabled: if the server is read-only, even a write token session has no write tools. get_status says so and how to turn writes on. wazap refuses to bind a non-loopback address without a read token. Agents that cannot carry a header sign in with OAuth instead.

Self-host

Run wazap on a server of your own when the agent is not on your laptop: another machine, a VPS, a client's infrastructure. The session stays on that server; nothing goes through a third party.

With systemd

npm install -g wazap-mcp
sudo useradd --system --home /var/lib/wazap --create-home wazap
sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
WAZAP_READ_TOKEN=$(openssl rand -hex 32)
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
END
sudo curl -fsSL https://raw.githubusercontent.com/razvangirgiz/wazap/main/deploy/wazap.service -o /etc/systemd/system/wazap.service
sudo systemctl enable --now wazap
curl -s http://127.0.0.1:8766/healthz

The unit binds loopback only. Put TLS in front with the two-line deploy/Caddyfile (caddy run --config deploy/Caddyfile after editing the hostname) or any reverse proxy, then point the client at https://your-host/mcp with Authorization: Bearer <read or write token>.

With Docker

git clone https://github.com/razvangirgiz/wazap && cd wazap
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

The container publishes 8766 on loopback only; add the same TLS proxy in front. Upgrading is git pull && docker compose up -d --build; the volume keeps the session.

From a machine without a public address

A laptop or a box behind NAT can still serve hosted agents through a tunnel, with no port opened and TLS done at the edge. npx wazap-mcp expose does the whole thing with Tailscale Funnel or Cloudflare Tunnel, whichever is installed. See Keep it running.

wazap keeps binding loopback either way; only the tunnel reaches it.

cloudflared tunnel login
cloudflared tunnel create wazap
cloudflared tunnel route dns wazap wazap.example.com
cloudflared tunnel run --url http://127.0.0.1:8766 wazap

Which clients can reach it

Claude Code, Claude Desktop, Cursor, Codex, VS Code, Poke and any client with an "MCP URL + header" field connect with the bearer token. Keep the read token in clients that only need to read; hand out the write token deliberately.

claude.ai Connectors, ChatGPT and some hosted agents will not take a static header. They want OAuth, which is the next section.

Hosted agents (OAuth)

Two more lines in the same .env turn wazap into its own OAuth 2.1 server:

WAZAP_PUBLIC_URL=https://wazap.example.com
WAZAP_OAUTH_PASSWORD=$(openssl rand -base64 18)

Then give an agent nothing but https://wazap.example.com/mcp. It finds the authorization server at /.well-known/oauth-protected-resource/mcp, registers itself (RFC 7591, so there is no client id to paste anywhere), and sends you to a page on your own host that asks two things: the password above, and whether this agent may only read or also send. A refresh token keeps the agent signed in until you revoke it; access tokens rotate every 24 hours on their own.

Tested against the flow claude.ai, ChatGPT and Poke use: S256 PKCE, public clients, /token with refresh, /revoke. The bearer tokens keep working next to it, so a laptop client on a header and a hosted agent on OAuth share one server.

What to know before exposing it:

• WAZAP_PUBLIC_URL must be https and a bare origin, no path: the endpoints live at its root. The password travels to it.
• The password is the whole identity layer. Use a long one. A consent page takes three wrong guesses and is gone; five from one address lock that address out for fifteen minutes; twenty from anywhere close the page for everyone for fifteen minutes.
• With OAuth on, /mcp never answers an unauthenticated request, whether or not a read token is set.
• Grants live in <data-dir>/oauth.json as hashes. Delete the file to sign every agent out at once, running server included; wazap status lists who holds one. Disconnecting an agent on its side revokes its refresh token and every access token it minted. A refresh token unused for ninety days is dropped.
• A read grant never sees a write tool, whatever scope the agent requested. The radio button on the consent page is the only thing that decides.

Outbound webhook

Live events POST to one URL. Off by default. History sync is not posted. Only message_received is posted unless you ask for more, because a consumer that answers every POST without reading event would otherwise answer the messages its own owner typed on the phone.

The event field names one of three. message_received is a message another person sent. message_sent is a message this account sent itself, typed on the phone or on another linked device; a message wazap sent through its own tools is not announced, so a consumer can never be made to answer itself. connection says the link came up, went down or expired.

Ask for the other two in WAZAP_WEBHOOK_EVENTS, comma-separated (message_received,connection), or say all for the three of them. Case does not matter and the spaces around a name are ignored. An unknown name fails wazap status, doctor and setup. An account carries its own list as webhook_events in accounts.json.

npx wazap-mcp config webhook on    # asks for URL + secret (secret is not echoed)
npx wazap-mcp webhook test         # POST a probe event
npx wazap-mcp webhook test --event connection   # needs connection enabled
npx wazap-mcp webhook test --account work
npx wazap-mcp config webhook off

On without a URL or secret fails wazap status, doctor and setup. A failed delivery retries twice (200 ms, then 500 ms), then sets webhook.last_error and leaves WhatsApp and MCP running. An account may set webhook_url, webhook_secret and webhook_events in accounts.json; those win over the global URL, secret and event list, and config webhook off --account work clears all three.

webhook test --event <name> posts nothing and exits non-zero when that event is not enabled, and says what to enable it with. While the webhook is on, wazap config prints the events it posts on an events: line.

HMAC: X-Wazap-Signature is sha256=<hex>, HMAC-SHA256 of the exact raw JSON body with the secret that signed it. Verify that raw body, not a re-serialized object. HTTPS only, except http:// on loopback.

text is a preview, cut at 2000 characters and ending in a single …. truncated is true when it was cut. For kind: "audio", text is the transcription when wazap auto-transcribed the note itself, which it does for incoming notes only; the event waits up to 60 seconds for those words. In every other case text is the [voice message · 0:42] placeholder: a note you recorded yourself, a note longer than 600 seconds, a note WhatsApp stated no duration for, and a transcription that failed. ts is the original local time with a numeric offset, kept for consumers already reading it, and timestamp is the same instant in UTC.

Events are not guaranteed to arrive in the order they happened. A message held for its transcript is overtaken by the messages behind it, so order by timestamp and not by arrival. Connection events are the exception: they are delivered in the order the link moved in.

A message another person sent:

{
  "event": "message_received",
  "from": "15550100",
  "chat_id": "15550100@s.whatsapp.net",
  "ts": "2026-09-08T17:00:00+03:00",
  "timestamp": "2026-09-08T14:00:00.000Z",
  "text": "hello, or a preview of something longer",
  "truncated": false,
  "kind": "text",
  "from_me": false,
  "is_self_chat": false,
  "message_id": "false_15550100@s.whatsapp.net_3EB0…",
  "account_id": "default",
  "account_name": "default"
}

A message sent from the phone, here in the "Message yourself" chat:

{
  "event": "message_sent",
  "from": "15551234",
  "chat_id": "15551234@s.whatsapp.net",
  "ts": "2026-09-08T17:04:12+03:00",
  "timestamp": "2026-09-08T14:04:12.000Z",
  "text": "call the notary at 14:00 on Wednesday",
  "truncated": false,
  "kind": "text",
  "from_me": true,
  "is_self_chat": true,
  "message_id": "true_15551234@s.whatsapp.net_3EB0…",
  "account_id": "default",
  "account_name": "default"
}

A connection change. status is linked, disconnected or expired; not_linked, linking and connecting post nothing, and two changes that mean the same status post once.

{
  "event": "connection",
  "status": "expired",
  "timestamp": "2026-09-08T14:10:00.000Z",
  "account_id": "default",
  "account_name": "default"
}

connection reports what the socket does while wazap is running. A clean shutdown posts nothing, and a crash posts nothing either, so silence does not mean the link is up. Poll get_status when you need to know that.

Settings

Flags beat environment variables, which beat <data-dir>/.env.

Known limitations

• Unofficial. Baileys reverse-engineers the WhatsApp multi-device protocol. This is not the WhatsApp Business API and Meta does not support it.
• Ban risk is real. Automated sending, bulk messaging or anything a human would not plausibly type can get the number banned, and that is not recoverable from here. The rate limit helps; it is not a guarantee.
• Media keys expire. WhatsApp drops old attachments from its servers, so download_media on an old message returns MEDIA_UNAVAILABLE.
• History is what the phone syncs. wazap sees the history WhatsApp hands the linked device, not your full phone archive. read_messages with before asks for more, within whatever WhatsApp still keeps.
• @lid ids. Newer accounts are addressed by a privacy id rather than a phone number. wazap translates them back to phone numbers when it has learned the mapping, and passes the @lid through when it has not.
• Names come from the phone's address book. WhatsApp delivers it as an app state sync, and only to a connection asking for it from scratch. If contacts read as phone numbers and get_status shows contacts_named: 0, ask for it again with the sync_contacts tool or wazap contacts resync.
• Calls are WhatsApp calls only. A call shows up as a message with type: "call", carrying its kind, direction, outcome and duration. WhatsApp's own call log and the missed-call notices arrive on their own; a call that starts and ends while wazap is running is recorded live, so calls placed or received while it is stopped can be missing entirely. A cellular call from the phone's dialler is never visible, on any device.
• Your phone must stay reachable. A linked device stops receiving once the phone has been offline long enough; get_status says so in hint.

Development

npm install
npm run typecheck
npm test                       # builds, then runs node --test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

npm test needs no WhatsApp session. The stdio smoke test spawns the built binary against a throwaway data directory and checks that an unlinked install still answers initialize, tools/list and get_status.

MIT licensed.