meirlabs
Meir RosenscheinHow Do You Connect an AI Agent to a WhatsApp Group?
You can't with the official WhatsApp API; it only creates its own invite-link groups and can't join one you already have. What works: a spare prepaid number, linked as a device to an agent runtime like OpenClaw on a small server, added to your group as a normal member. It rides an unofficial client, so treat that number as expendable; everything it captures lives on your server, not in WhatsApp.Launch offer: Early clients get 50% off their first build, so your real cost is about half these figures. Book a free AI plan to lock it in.
I built this for my own product's founder group, two people running a company out of one WhatsApp thread with every task and document drowning in it. The goal was a quiet third member that turns messages into tickets. Here's the setup that works.
Why can't you just use the official WhatsApp API?
Meta's Groups API only lets a business create its own groups, joined by invite link and capped at 8 people. There's no endpoint for joining a group that already exists between two normal accounts. That one limit rules out every official-API platform for this job. Anything that can join your group is riding an unofficial client underneath.
How do you set it up, step by step?
Three pieces do the work: a dedicated phone number added to your group as a normal member, an unofficial linked-device client built on Baileys (a reverse-engineered WhatsApp Web library) that lets a server send and receive as that number, and an agent runtime, OpenClaw, as the brain. Six steps, about two hours.
-
Get a dedicated number. A prepaid eSIM or SIM with a real mobile number, not a VoIP one (WhatsApp blocks those). Register a fresh WhatsApp account on it; the Business app lets it share a phone with your personal account.
-
Stand up OpenClaw and connect it to Claude. Any $5–10 a month VPS is plenty. Install OpenClaw, then give it your Anthropic API key so its agent runs on a Claude model. WhatsApp ships as an OpenClaw plugin. This OpenClaw setup walkthrough covers install and pairing end to end.
-
Pair the number. Start the WhatsApp login and scan the QR from the bot's phone under Linked Devices, exactly like WhatsApp Web.
-
Add the bot to your group. Add its number like any member and it sees every message. Admit that one group and set the agent to read all of it, not just messages that tag it.
-
Give it instructions and tools. This is the whole product; the other five steps are plumbing. The system prompt classifies every message (task, decision, question, document, fyi) and carries the behavior rules. These took real debugging; paste them close to literally:
- "Any text you produce gets posted to the group. Between tool calls, output nothing; your only text output is a silent end token."
- "Stay silent by default. React only after you actually do something, and the reaction is the receipt: a checkmark when you create a ticket, a folder when you file a document. A decision, a question, small talk, a voice note, or a duplicate of something already tracked gets nothing at all."
- "Before creating a ticket, search for an existing one. One ask must never spawn five tickets."
- "Ask 'am I being addressed?' before you classify anything, and make it a bright-line test: yes only if there's an explicit @mention of you, the word 'bot' spoken to you directly anywhere in the message (first word, last word, or mid-sentence: 'tell me, bot, what's open'), a reply to a message you sent, or a message that directly reacts to the last thing you said, a correction or a follow-up question, one hop only. Talking about you in the third person ('the bot didn't respond') is not talking to you, and when you can't tell which it is, it isn't. A plain imperative between the two humans ('fix the button') is them assigning work to each other, never a request to you."
- "A mention of you arrives as raw text, not metadata: the literal token
@<bot-LID>, WhatsApp's internal ID for your account, which is not your phone number and not your display name. These instructions spell out both your ID token and your number verbatim; either one anywhere in a message means you're addressed, and@plus any other number is a human mentioning a human. A bare mention with no ask still gets one short reply inviting the ask, never silence."
Three of those are scar tissue. The first version reacted to every single message, which in a two-person founder group is just noise, so silence became the default and reactions became receipts-only. The addressed test had to move ahead of classification and become bright-line, because the cheaper fallback models kept reading plain imperatives between the two humans as requests to the bot. And the mention rule exists because the bot once ignored a real @mention: the client forwards no mention metadata at all, just that raw internal-ID token, so "respond when @mentioned" is an instruction the bot literally cannot follow until you spell the token out. The tools are small scripts the agent calls: create a Linear ticket, file a shared document, search past messages. Reminder requests route to the agent runtime's own scheduler, not the ticket system. Small scripts beat heavy integrations.
-
Add the safety net. Log every inbound message to your own database, separate from the agent, and reconcile it against tickets daily. This is the step people skip and regret.
Out-of-pocket cost is $6–12 a month all-in: a dollar or two for the number, the rest for the VPS. Everything else is model usage on your own API key, scaling with how busy the group is.
What does it actually do with the messages?
Reading is the easy part; the value is what it does next.
-
Tasks become Linear tickets. "Send the investor deck by Friday" becomes a ticket in the right Linear team. Linear stays the to-do list; the chat goes back to being a chat. When a task wraps a real client's details, the ticket describes the technical problem and leaves the client out of it.
-
It stays silent by default and reacts only as a receipt. The reaction lands only after it actually does something: a checkmark when it creates a ticket, a folder when it files a document. Finding an existing ticket isn't work, so it earns silence too, the same as decisions, questions, small talk, and voice notes, so the only marks in the thread are proof that work happened.
-
Documents land in a searchable library. A dropped PDF gets read, summarized, and indexed, findable later by what's in it. Sensitive client material is the deliberate exception: it's never filed and never ticketed.
-
It answers questions about the group's history. Mention it with "what did we decide about pricing" and it replies from the full log, then goes quiet.
-
It answers from the team's meeting notes too. Ask "what did we decide in the meeting about pricing?" and it answers from the AI notetaker's notes and tells you the date of the meeting it's quoting, so the answer is checkable.
-
It can explain itself. Ask "what can you do?" and it lists what it handles silently, what you can ask it for, a glossary of its emoji receipts, and an explicit line that the silence is intentional and means "seen, nothing to do."
How do you contain the ban risk?
Accept it, then isolate it. Unofficial clients break WhatsApp's terms, and ban waves catch even low-volume accounts, so treat the bot's number as expendable. That's the whole strategy: your personal and business numbers never touch the automation, and a banned bot is a new prepaid SIM and a fifteen-minute re-pair. Keep a spare. Everything that matters, tickets, documents, message history, lives on your server and in Linear, not in WhatsApp.
Can one bot serve several groups and projects?
Yes: sessions are per group, so one bot number can sit in many groups without contexts bleeding, and a per-group system prompt ("this group is project B, tickets go to that team") covers most cases. One wiring gotcha: a Linear API key only sees its own workspace, so a project in a different Linear workspace needs its own key. It's still one number though, so a ban takes every group down at once; keep external collaborators on a separate number. The per-group boundary has to extend to everything the bot reads, not just what it writes: each group's bot is scoped to its own project's meetings, so the bot in one group can never surface another project's. Once one number serves several groups, that scoping is the whole ballgame.
What does it take to plug in an outside tool like meeting notes?
Less work on the reading side than you'd think, more on the sorting side. The meeting-notes API has no search, no way to filter by who attended, and a list view that returns only titles and dates, so the bot keeps its own local, searchable cache, refreshed on a schedule, and classifies each meeting to a project itself. You also can't write the categories back: the meeting app's folders are read-only to the API, so the project mapping has to live in your own store. Anyone assuming they can auto-file meetings inside the meeting tool hits that wall. The same shape covers other internal systems, so "how many signups this week?" is the bot calling an admin endpoint you already have with a service token, not a new pipeline.
What breaks first?
Every one of these bit me, and each failed silently before it got a rule:
- The bot narrated its work into the chat. Fix: the silence rule from step 5, exactly as quoted.
- The bot reacted to every single message. In a two-person group, an emoji on every line is its own kind of noise. Fix: make silence the default and reactions receipts-only, and settle "am I being addressed?" as a bright-line test (an @mention, "bot" as a direct address anywhere in the message but never a third-person "the bot", a reply to the bot, or a direct reaction to the last thing the bot said) checked before any classification, so a plain imperative between the two humans isn't mistaken for a request to the bot.
- The bot ignored a real @mention. WhatsApp delivers a mention as a raw
text token,
@plus the bot's internal ID, which is neither its phone number nor its display name, and the client forwards no mention metadata alongside it. So "respond to @mentions of you" was a rule the bot couldn't satisfy. Fix: have someone tap-mention the bot once, read the literal token out of the message log, and paste both it and the bot's number verbatim into the instructions. - Emoji reactions failed silently in groups. Fix: don't pass an explicit message ID in the reaction call; let the client work out the participant itself.
- A message vanished during a session restart. Fix: the step 6 log and daily reconcile; the agent can fail, the log can't.
- Timeouts pushed work to the cheapest fallback model, which follows rules worse. Fix: raise the timeout, put a mid-tier model ahead of the cheap one, and write every rule assuming the weakest model is the one reading it.
- Loose keyword matching filed meetings under the wrong project. AI notetaker summaries mention words like "legal" or "client" in passing, which is enough to fool a fuzzy match. Fix: keep the matching strict and let anything ambiguous sit in an unsorted pile a human reviews. A guess that looks right is worse than an obvious inbox.
- A deliberately silent bot is undiscoverable. Nobody in the group knew what it handled, and its emoji looked arbitrary. Fix: teach it to answer "what can you do?" with a glossary of its receipts and a line saying silence is intentional. Make that a required section of any group bot's instructions.
A simple rule to start: give the bot its own expendable number and its own independent message log. Everything else that goes wrong is recoverable from those two.
Can you skip the setup and hand it to Claude Code?
Yes, and it's the fastest path if you already use Claude Code. I packaged this whole playbook, architecture, OpenClaw config, prompt rules, every gotcha, into an installable skill. Install it and ask Claude Code to set the bot up:
npx @meir-labs/skill-whatsapp-group-agent
The full skill is here: whatsapp-group-agent. Same one I run, minus my own server specifics.
Want this running in your group without building it yourself?
That's the part I do. If you'd rather not stand up a server and tune prompts until the bot behaves, I'll set it up for you: your group, wired into your Linear, tickets appearing from chat by the end. The free AI plan below is where it starts.