DEV Community

Bubbles Studio profile image Kjudeh
Kjudeh for Bubbles Studio

Posted on

An AI receptionist on a real WhatsApp number: architecture, routing logic, and failure modes

#whatsapp #ai #automation #selfhosted

In most of the Gulf and Levant, WhatsApp isn't a support channel — it's the front desk. Customers ask prices, book appointments, and choose between competitors based on who answers first. Which makes the default setup remarkable: a human checking a phone between tasks, going silent at 8pm.

This post walks through the architecture of a self-hosted AI receptionist on a normal WhatsApp number — what the pieces are, why each exists, and the failure modes to design around. At the end there's a one-click version if you'd rather skip the assembly.

The architecture

Four services:

WhatsApp ⇄ Evolution API → webhook → n8n workflow → LLM (Claude/GPT)
                ↑                        │
                └── send reply ──────────┘
        Postgres (sessions, messages) · Redis (instance cache)
Enter fullscreen mode Exit fullscreen mode
  • Evolution API (9k★) speaks the WhatsApp Web protocol — you pair it with a QR scan like WhatsApp Web, and it exposes a REST API + webhooks for messages.
  • n8n hosts the receptionist logic as a visual workflow: filter → route → LLM call → reply.
  • Postgres + a small volume persist the session, so redeploys don't ask you to re-scan the QR code.
  • The LLM is yours — an Anthropic or OpenAI key, with the business context in the system prompt.

The routing logic that makes it a receptionist (not a toy)

The naive version — "forward every message to an LLM" — fails in production within a day. The workflow needs four branches:

1. Ignore what should be ignored. Group messages, your own outgoing messages, non-text payloads. Skipping this floods your LLM bill and spams groups.

2. Human handoff, on a keyword. When a customer types "human" (or your word of choice), the bot acknowledges, stops replying in that thread, and notifies your team. An AI that traps customers in bot-loop hell costs more goodwill than it saves labor.

3. Office-hours awareness. Out of hours, an instant "we're closed, here's when we open, leave your message" beats an AI improvising commitments at 3am.

4. Only then, the LLM. With a system prompt carrying the business's real facts (services, prices, policies, tone), a length cap, and instructions to offer the handoff word when unsure. Bilingual businesses: prompt it to answer in the customer's language — Arabic in, Arabic out.

Deployment failure modes to design around

  • Session loss. If WhatsApp auth lives only in the container, every redeploy needs a QR re-scan. Persist sessions in Postgres and a volume.
  • Version drift. Pin images by digest. (If you use Evolution API specifically: stay on the v2.3.x line — v2.4.0+ requires a license activation.)
  • The unofficial-client caveat, honestly: this rides the WhatsApp Web protocol, not the official Business API. Meta can restrict accounts that spam. Use a dedicated number, answer inbound rather than broadcasting, and use the official API for regulated workloads.

The one-click version

We packaged this exact architecture — Evolution API (pinned v2.3.7), n8n with the four-branch receptionist workflow pre-loaded and auto-activated, Postgres, Redis, session persistence — as an open-source (MIT) Railway template:

Deploy, paste an LLM key, scan one QR code, and message your own number.

And if you'd rather have it done for you — installed on your number, persona tuned to your business in Arabic and English, live in 48 hours, optionally managed — that's what we do at Bubbles Studio.

Questions welcome in the comments — and the repo takes issues and PRs.

Top comments (0)