Most "WhatsApp chatbot" tutorials start with the official WhatsApp Business API: a Meta developer app, a verified business, webhook setup and per-conversation fees. That is the right choice for large companies. But a lot of small businesses (a bakery, a clinic, a phone shop) just want an assistant on the number their customers already have.

I've been working on Wapzen, a WhatsApp AI agent that runs on an existing number. Here is how that kind of system fits together, and the problems you hit that tutorials don't mention.

1. Connecting: the linked-device protocol

WhatsApp lets a phone link up to four extra devices (that's how WhatsApp Web works). Open-source libraries such as Baileys speak that protocol, so a server can act as one more linked device.

Two ways to link:

  • QR code: the server shows a QR, the user scans it under Linked devices.
  • Pairing code: the user types their number and enters an 8-character code on the phone. We found this works much better for people who only have one phone and can't scan their own screen.

Things that bit us:

  • Session keys must be saved atomically. If the process dies between writing two key files, the session breaks and the user has to scan again.
  • The WhatsApp Web version matters. Connect with an outdated version and the server rejects you with a 405 before any QR appears. Fetch the current version at runtime instead of hard-coding it.
  • Deploys need a handover plan. During a rolling deploy two instances can try to own the same session. One of them gets kicked, so only one instance may hold a session at a time.
  • Not official. This approach isn't an official Meta product and businesses should know that. The Business API is the official route.

2. Answering: an agent, not a decision tree

Each incoming message goes to an LLM with:

  • a system prompt the business owner writes (what they sell, prices, hours, tone)
  • a knowledge base: the owner's documents chunked and embedded in a vector index, searched at reply time
  • the recent conversation: the last ~20 exchanges word for word, with older history folded into a rolling summary so long chats don't blow up the context

Customers also send voice notes and photos, so those get transcribed or described before the model sees them. In many markets voice notes are half the traffic.

3. Tools: where the real value is

Answering questions is nice. Doing things is better. The agent gets tools such as:

  • create_order: with a forced confirmation step. The model has to read the full order back and get a "yes" before the tool will save it. If the customer then says "make it 3, not 2", the open order is amended instead of a duplicate being created.
  • send_file: sends the owner's product photos or PDFs when the request matches the file's description.
  • read_website: reads pages on the business's own site (same domain only, to keep it from fetching arbitrary URLs).

4. Guardrails you will need on day one

  • Loop guard. Two bots replying to each other will happily chat forever. Detect echoes and floods per contact and switch the AI off for that chat.
  • Per-contact off switch. Owners want to handle some customers personally.
  • Groups off by default, and only reply when tagged or replied to.
  • Ignore Status updates. WhatsApp Status posts arrive like messages, and replying to them (or acknowledging them wrongly) causes trouble.

Try it

If you want to see the result without building it yourself, Wapzen is free to start: link a number, describe your business, and the agent starts replying. There's also a write-up on using it as a WhatsApp Business API alternative, including when you should still use the official API.

Happy to answer questions about the linked-device side in the comments.