English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Türkçe · Русский · Tiếng Việt · ไทย · Deutsch · Español · Français · Українська · Polski · Português (Brasil) · العربية · فارسی · Bahasa Indonesia · Italiano · Ελληνικά

WAB bot

One business's WhatsApp number, one AI agent over MCP, on your own Cloudflare account.

WAB bot: AI auto-reply and voice answering for business chat on the WhatsApp Cloud API. A small, single-tenant bridge: customers message (or call) your WhatsApp Cloud API number, your agent answers through guarded tools, and nothing leaves your accounts.

Quick start · How it works · What it can do · Worked examples · FAQ · Documentation

Your customers write to your business's WhatsApp number. Meta delivers each message to a Worker in your own Cloudflare account, which stores it and sends your AI agent a content-free wake-up. The agent (any MCP-capable agent) claims the conversation, reads the history, and replies through send_reply. The bridge, not the agent, holds the WhatsApp token and enforces every send guard. Staff can pause, take over, or erase a conversation from /admin.

One deployment per business: its own Meta app, number, tokens and Cloudflare account. There are no secrets in this repository.

Quick start

You need: a Cloudflare account you own, Node.js 20+ (22 recommended), a Meta developer account and WhatsApp Cloud API setup (checklist), a new number never registered in any WhatsApp app, and an agent that can use MCP and be woken by a webhook (wake routine). You pay Meta and your own AI plan directly; the Workers Free plan needs no payment method for what this template uses (limits and terms).

1. Check it offline (no account, no network)

git clone https://github.com/wabbot-dev/wab-bot.git && cd wab-bot
npm ci
npm run check          # typecheck, 353 logic tests, 65 workerd tests, docs check
npm run build          # wrangler deploy --dry-run: bundle and binding check
npm run smoke:local    # wrangler dev --local with random fake secrets

2. Deploy to your own Cloudflare account

bash scripts/deploy-cloudflare.sh --dry-run                  # prints the plan, makes no call
bash scripts/deploy-cloudflare.sh --name my-business-wa      # lowercase letters, digits, dashes

The script logs you in with wrangler login --device (you approve a code in your browser; it never creates an account), deploys, generates the bridge's own tokens, and uploads secrets on stdin. Other routes (Cloudflare API without a login, self-provisioned secrets) are in docs/DEPLOY.md. The setup has been proven live on 2 different accounts (status). If a required secret is skipped, the script names it and exits non-zero. A liveness check answers at /api/health with only ok and version (no secrets, counts or messages). On a brand-new Cloudflare account, which has no workers.dev subdomain, the deploy scripts register one first when an API token and the account id are exported (an existing subdomain is never changed). The API token needs only the Workers Scripts Edit permission on your own account; keep the show-once token page open until the token is stored and verified (details in docs/CLOUDFLARE.md and docs/DEPLOY.md). The account may already have Workers: list them first and never touch what you did not create.

3. Connect Meta and your agent

Follow docs/META-CHECKLIST.md (you create the Meta accounts, verify your business and type the SMS code yourself), run node scripts/meta-setup.mjs on your own computer, and point your agent at https://<worker>.<your-subdomain>.workers.dev/mcp with Authorization: Bearer <MCP_TOKEN>.

4. Stay in test mode until a message round-trips

Safe defaults: LAUNCH_MODE=test (replies go only to TEST_RECIPIENTS), auto-reply paused, templates off, the in-Worker Meta setup route off. Send one message from your phone, watch it arrive in /admin, let the agent answer, and only then go live deliberately.

Related MCP server: whatsapp-mcp

How it works

flowchart LR
  C[Customer on WhatsApp] --> M[Meta Cloud API]
  M -- "signed webhook" --> W[Your Worker + SQLite Durable Object]
  W -. "content-free wake" .-> A[Your AI agent]
  A -- "MCP: claim, history, send_reply, finish" --> W
  W -- "guarded send" --> M
  S[Staff] -- "/admin" --> W

Every webhook must carry a valid X-Hub-Signature-256 over the raw body. One SQLite row per conversation keeps requests independent; a lost race re-reads and retries. The wake POST carries ids and counters only, never message text. Boundaries and ownership: docs/ARCHITECTURE.md. Storage, retention and wake: docs/STATE-STORE.md.

What it can do

Not included: video understanding (a video is noted, not watched), groups, outbound calls, audio recording, a settings page, preset routines, multi-tenant hosting. See docs/ROADMAP.md.

Worked examples

One customer turn over MCP (placeholders only; the agent does this through its MCP client):

MCP=https://<worker>.<your-subdomain>.workers.dev/mcp
call() { curl -s "$MCP" -H "Authorization: Bearer $MCP_TOKEN" -H 'content-type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"$1\",\"arguments\":$2}}"; }
call list_pending '{}'
call claim_conversation '{"conversation_id":"c_<id>"}'                       # returns a lease
call get_history '{"conversation_id":"c_<id>","lease":"<lease>"}'            # customer text is wrapped as untrusted
call send_reply '{"conversation_id":"c_<id>","lease":"<lease>","text":"Hello, how can I help?"}'
call finish_conversation '{"conversation_id":"c_<id>","lease":"<lease>"}'

While LAUNCH_MODE=test or auto-reply is paused, send_reply answers blocked_test_mode_recipient_not_allowlisted or blocked_auto_reply_paused instead of sending. The guard order and every error string: docs/CONFIGURATION.md.

Erase one customer:

curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" https://<worker>.<your-subdomain>.workers.dev/api/admin/conversations/c_<id>
# {"ok":true,"deleted":true}   (404 if unknown or already erased)

Remove everything: bash scripts/teardown-cloudflare.sh (asks you to type the Worker name; deletes the Worker and every stored conversation, nothing else).

FAQ

Who owns the Cloudflare account? You do: you accept the terms, you pay if you ever pay, and you can delete it. An assistant may create the Cloudflare and xAI accounts for you only with your written consent and with you made owner or admin; you add any card yourself. Meta accounts, Business Verification and the SMS code are always yours (details and the Cloudflare terms caveat).

Is the Free plan allowed for a business? In the Cloudflare terms read on 2026-10-17 the Free services carry no personal-use-only clause, with two restrictions that matter here (no card collection, no protected health information without Cloudflare's written consent). Not legal advice; re-check (commercial use).

Can I use my existing WhatsApp Business app number? No. The Cloud API number must never have been registered in a WhatsApp app; coexistence is out of scope. Bring your own SIM or line and type its code yourself.

Does it answer calls? Yes, inbound only, and only when you open the gate: calling is off by default, stays off on a real number until your Business Verification is complete and you say go, and runs in short windows you arm. It uses xAI Grok Voice on your own xAI account (about $0.08 per minute). Calls from this code were answered live on Meta's test number on 2026-10-17 (two-way conversation, transcripts stored); it has not run on a business-verified production number, and audio recording is not supported (voice).

Which agent works? Any agent that can speak MCP over HTTP and be woken by a webhook. It has been tested against direct JSON-RPC calls, not against real MCP clients (wake routine).

How much volume? Single tenant, one Durable Object: small-business volumes. Roughly 30,000 messages a day fit the Free Durable Object quota by our live measurement; many simultaneous messages in one conversation can return 503 and Meta redelivers (status).

Is it proven in production? The design it comes from is reported to be (owner-reported, date TBD). This Cloudflare port is not. Status says exactly what each level means.

Limits and good practice

• Independent project. WAB bot is unofficial: it is not affiliated with or endorsed by Meta, WhatsApp or xAI. WhatsApp and Grok are trademarks of their owners.

• Meta's rules apply. Your use of the WhatsApp Cloud API follows Meta's terms, messaging policies and per-number rules, and calling on a business number needs Meta Business Verification.

• One number per bot. One deployment serves one business and one WhatsApp number, with its own Meta app, tokens and Cloudflare account. If the Meta app you point a new bot at already serves another bot, setup changes nothing and asks you to create a new Meta app in the same business portfolio.

• Calling is yours to switch on. It is off by default; you open it and name the number, and calls use your own xAI credits (about $0.08 per minute).

• Inbound calls only, no audio recording. Outbound calls and recording audio are not supported. A text transcript is kept by default, and you can switch it off.

• SIP and the Graph calling API are mutually exclusive per number. While a number uses SIP for calling, as this bot does, Meta's Graph calling endpoints are not available on it.

• Keep a fallback contact path. Publish another way to reach you, such as a phone line or an email, and keep staff able to take over any conversation.

What is supported and what is not: capabilities. Practical answers: troubleshooting. Calling in detail: voice.

Documentation

docs/index.md lists every page. Start with STATUS, then DEPLOY, META-CHECKLIST, CONFIGURATION, PRIVACY and TROUBLESHOOTING. Also: AGENTS.md for AI coding agents, SECURITY.md, CHANGELOG.md, THIRD_PARTY_NOTICES.md.

Disclaimer

This is preview software for lawful business messaging. You are responsible for your deployment, credentials, customers' data, recording and AI-disclosure rules, and your Meta and Cloudflare terms. No warranty. Read DISCLAIMER.md.

Contributing

Focused fixes, docs corrections and tests are welcome; read the contribution scope and the PR readiness rules first. AI-assisted PRs need a named human owner. Security problems: SECURITY.md.

License

MIT, Copyright (c) 2026 wabbot-dev.