The Brief

A personal experiment: can a spare WhatsApp number answer direct messages with an AI model, without a Meta developer account or business verification, and with limits that keep cost and abuse bounded? The result is a small Node.js project, published under the MIT licence.

Where It Started

The repository began as a fork of finereli/whatsapp-mcp, an MIT-licensed project that lets an AI assistant read and search a WhatsApp history. That design only connects when an assistant asks for data, so it cannot answer messages as they arrive. The forked code was replaced by a long-running bot; only the licence remains from the original, and the earlier code is still in the git history.

How It Works

A Node.js process links to WhatsApp as a linked device through Baileys, an unofficial TypeScript library for the WhatsApp Web protocol. Linking uses a pairing code entered on the phone, or a QR code. For each incoming direct text message, the bot sends the recent turns of that chat to an OpenAI-compatible chat-completions endpoint (DeepSeek by default, but any compatible provider works), shows a typing indicator for a random delay of two to five seconds by default, then sends the reply. Groups, status updates, newsletters and the bot's own messages are ignored.

Guardrails

The bot answers only numbers on an explicit list, which is empty by default; an asterisk opens it to anyone. Two sliding-window caps then limit replies per sender per hour and across all chats per hour (10 and 30 by default), so one chatty number cannot spend the whole model budget. Only one reply per chat is generated at a time. Conversation memory is the last ten exchanges per chat, held in memory and lost on restart. The bot has no tools, so a hostile message can change what it says but not what it does. The API key file and the WhatsApp session folder are git-ignored, and unit tests cover the allowlist, the rate limiters and the history, though not a live WhatsApp connection.

Limits

Baileys is not affiliated with WhatsApp, its maintainers say they do not condone uses that break WhatsApp's terms, and WhatsApp's Terms of Service prohibit auto-messaging. The linked number can be banned, so the bot is meant for a spare number, personal use and experiments, not customer service. Message text is sent to the model provider. It currently runs on a local machine rather than an always-on host. For a business, the official WhatsApp Business Platform is the supported route; the trade-offs are covered in WhatsApp AI Bots in 2026: Official Cloud API or Baileys?