WhatsApp AgentKit: a Claude Code scaffold that interviews you and writes the bot

The plumbing problem WhatsApp AgentKit was built to remove

The README is blunt about the motivation: most of the work in standing up a WhatsApp agent is not the AI, it is webhooks, signatures, tokens, retries and deployment. The kit ships that layer pre-written and audited, so the only thing left to supply is what nobody else knows, which is how your business works. The target reader is stated explicitly: builders in LATAM, which is why the documentation, the interview and the generated prompts are in Spanish. That is a real constraint, not a cosmetic one. If you cannot read Spanish well enough to answer a business interview and review generated YAML, this kit will be awkward even though the Python it emits is ordinary. It is aimed at people who do not write code. The README says you answer questions, not write code, and the five-phase flow is designed around that promise. The trade is that you hand the architecture decisions to a model. You get a running agent quickly, and you get whatever structure Claude Code chose on your behalf.

Five phases, from environment check to a live webhook

start.sh only verifies the environment. The real system begins with /build-agent inside Claude Code, which reads CLAUDE.md and runs five phases. Phase 1 checks Python 3.11+, creates folders, installs dependencies and prepares .env. Phase 2 is a ten-question interview covering business name, what it does, the agent's purpose, its name, tone, opening hours, price or menu files, your Anthropic API key, and which WhatsApp service to use. Phase 3 writes the project: agent/main.py for the server, brain.py for the Claude call, memory.py for per-customer history and event deduplication, tools.py for business-specific tools, and a providers/ directory with base.py, __init__.py and either zernio.py or meta.py. It also writes config/business.yaml, config/prompts.yaml, a knowledge/ folder for your files, tests/test_local.py, a Dockerfile and docker-compose.yml. Phase 4 is a terminal chat where you type as a customer. Phase 5 walks you through pushing to GitHub, connecting Railway, loading environment variables and configuring the webhook. The generated layout is the contract. If you later edit files by hand, you are editing output, not source, and the next /build-agent run has no documented way to preserve your changes.

Why the webhook answers before it thinks

The message flow is the most interesting design decision in the kit. A customer message hits your provider, which POSTs to /webhook. main.py verifies the signature, providers/ normalizes the payload into a common shape, memory.py checks whether that event was already processed and discards duplicates, and main.py returns 200 immediately before queueing the work. Only then, outside the webhook cycle, does memory.py fetch that customer's history, brain.py call Claude with the system prompt plus history plus message, and providers/ send the reply back. The README gives the reason: providers expect an acknowledgement within about five seconds and will retry the same message up to seven times if they do not get one, while a Claude call takes longer. Without the early 200, the customer would receive duplicates. That ordering also means a crash after the 200 leaves the message unanswered with no retry coming from the provider. The README does not document a queue durability guarantee, so treat the acknowledgement as a promise you have to keep yourself.

Installing it and running a first local chat

The README gives three commands for setup. The first clones the repository and moves into it, the second runs the environment check. You should see it confirm Python 3.11+, create folders, install dependencies and prepare .env.

# Clone the repository and run the environment check
git clone https://github.com/Hainrixz/whatsapp-agentkit.git
cd whatsapp-agentkit
bash start.sh

Next, open Claude Code and issue the build command. From there Claude Code runs the ten-question interview and generates the project tree described above.

# Open Claude Code, then run inside it:
claude
/build-agent

Before the interview reaches the Anthropic key question, copy the environment template. The file documents ANTHROPIC_API_KEY, ANTHROPIC_MODEL (default claude-sonnet-5), ANTHROPIC_EFFORT (low, medium or high), WHATSAPP_PROVIDER (zernio or meta) and the matching provider keys.

cp .env.example .env

After phase 3, phase 4 gives you a terminal chat driven by tests/test_local.py. You type as a customer and the agent replies using your business.yaml and prompts.yaml. The README shows a short exchange about opening hours and the price of an americano, with the agent answering from your knowledge files and offering to hold one. If a reply is wrong, you tell Claude Code and it adjusts the prompt or the config in place. Nothing here is verified against a live provider until phase 5.

Zernio or Meta Cloud API, and what switching costs

The kit abstracts the provider behind providers/base.py, with an adapter per service, and picks one automatically at runtime. The README recommends Zernio for almost everyone. Zernio runs on top of Meta's WhatsApp Cloud API and handles the connection, so you do not need a Facebook Business app, you skip App Review, and business verification happens through Embedded Signup. Its sandbox gives a shared test number with 50 free messages per 24 hours and no card, which is how the README suggests seeing the agent work today. In both paths you still pay Meta for conversations. Direct Meta Cloud API means you build the Facebook Business app and go through App Review yourself, in exchange for full control over the integration. The README says migrating later is a single sentence to Claude Code, quoted as "quiero migrar de Zernio a Meta Cloud API". That is a claim about the generator, not a tested migration path, and the README does not document what happens to an in-flight conversation or to stored history when the adapter changes.

Where this kit is the wrong tool

The dependency on Claude Code is the sharpest limitation. There is no documented path to run the generator without it, and the five phases assume an interactive session where a model asks and you answer. If your organisation blocks third-party coding agents, or you want the setup to run in CI, this kit does not fit. Second, the output is a starting point with no upgrade story. There are no retrieved releases, and the README does not describe how generated code tracks upstream fixes. Because the generator writes main.py, brain.py and memory.py into your project, pulling later improvements means regenerating and reconciling by hand. Third, the interview assumes a small business with hours, prices and a menu. A support agent that must query an order database, respect per-user permissions or escalate to a human has no matching question in the ten listed, so you would be extending tools.py and prompts.yaml yourself, which is exactly the work the kit claims to remove. Fourth, the README does not document rollback, rate limiting on your own webhook, or what happens when the Anthropic API key hits its spend limit mid-conversation.

Alternatives and the licence position

The obvious alternative is the WhatsApp Cloud API directly, which is what the kit's own meta.py adapter wraps. Going direct means you write the webhook handler, signature verification, deduplication and retry-tolerant acknowledgement yourself, and you own the Facebook Business app and App Review. You gain control over the exact request path and lose the pre-built normalisation layer. A second alternative is a general-purpose bot framework with a WhatsApp connector, where you assemble the pieces from libraries and keep the architecture in your own hands. The difference in approach is who makes the design decisions: this kit has Claude Code make them from your interview answers, while a framework leaves them to you. On licensing, the repository is MIT, so you can use, modify and redistribute the generated code and the kit itself, including commercially, provided the licence and copyright notice are preserved. That is the standard MIT grant and nothing in the README adds restrictions. It is not legal advice; if you redistribute the kit inside a product, read LICENSE rather than this summary. The WhatsApp side is separate: Meta's terms govern your number and messaging, and the README states that conversation costs are paid to Meta in both provider paths.

Editorial conclusion

Adopt it if you already pay for Claude Code, can answer ten questions about your business in Spanish, and want the webhook, signature check, deduplication and provider adapters handled for you rather than written from scratch. Skip it if you cannot or will not run Claude Code, if you need a documented upgrade path between releases, or if your stack is not Python. Before committing, verify three things in this order: that start.sh completes on Python 3.11+, that your chosen provider (Zernio or Meta) is actually reachable from your host, and that a duplicate webhook delivery is discarded by memory.py rather than answered twice.

Frequently asked questions

Official sources

1. Hainrixz/whatsapp-agentkit on GitHub
2. Issues
3. License: MIT
4. Project website
5. README