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

Kjudeh — Tue, 25 Aug 2026 21:13:39 +0000

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)

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: https://railway.com/deploy/whatsapp-ai-receptionist?referralCode=qxxcuG
Source + workflow JSON: https://github.com/Kjudeh/whatsapp-ai-receptionist

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.

Running n8n in production: queue mode, workers, and the settings that keep it alive

Kjudeh — Tue, 25 Aug 2026 19:21:55 +0000

Self-hosted n8n has a failure mode almost everyone hits eventually: everything runs fine for months, then one day the editor won't load, webhooks time out, and workflows silently stop. It's rarely a mystery when you dig in — it's almost always one of two things:

Single-instance execution. By default, n8n executes workflows in the same process that serves the UI and receives webhooks. One heavy execution (a big loop, an AI agent chain, a large file) and everything else starves.
The unbounded executions table. Every run writes execution data to your database. With no pruning, the table grows until Postgres becomes the bottleneck — or the disk fills.

Both have first-class fixes in n8n itself. They're just not the defaults. This post walks through the production setup n8n's own docs recommend — queue mode — plus the hardening settings that prevent the slow-motion failures.

How queue mode works

In queue mode, n8n splits into two roles:

The main instance serves the editor UI, receives webhooks, and manages schedules — but executes nothing. When a workflow should run, it pushes a job onto a Redis queue (Bull).
One or more workers pull jobs from the queue and execute them.

Webhook/schedule → main instance → Redis queue → worker(s) → Postgres

The practical consequences:

A heavy execution can't freeze your editor or drop incoming webhooks — intake and execution are different processes.
Scaling is horizontal: more load → more worker replicas. Workers are stateless (all state lives in Postgres), so replicas "just work".
A worker crash loses nothing: queued jobs are picked up when a worker returns.

The core configuration

Both main and workers share most configuration. The critical rule: main and workers must run the same n8n version and the same encryption key, or credentials break in confusing ways.

# Shared by main + workers
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=<postgres-host>
DB_POSTGRESDB_DATABASE=<db>
DB_POSTGRESDB_USER=<user>
DB_POSTGRESDB_PASSWORD=<password>
N8N_ENCRYPTION_KEY=<same value everywhere!>

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=<redis-host>
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=<redis-password>

# Main instance only
N8N_WEBHOOK_URL=https://your-domain/
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true

# Workers: start with `n8n worker`; enable its health endpoint
QUEUE_HEALTH_CHECK_ACTIVE=true

The worker is the same image/binary started with n8n worker — it connects to the same Postgres and Redis and begins consuming jobs (default concurrency: 10 parallel executions per worker).

The hardening most setups skip

Execution pruning. This is the one that kills instances. Cap the history:

EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=336        # keep 14 days
EXECUTIONS_DATA_PRUNE_MAX_COUNT=50000

Database backups you can actually restore. Workflows, credentials, and history all live in Postgres — it's the single point of loss. A compressed nightly pg_dump to any S3-compatible bucket costs cents; the part people skip is verifying restores. A backup you've never restored is a hope, not a backup.

Boring but worth setting: N8N_DIAGNOSTICS_ENABLED=false (telemetry off), pin your n8n image by version and digest so main and workers can never drift apart, and keep Postgres/Redis off the public internet.

Scaling checklist

When executions start queuing up:

Add worker replicas (they're stateless — this is safe).
Watch Postgres — execution writes are the next bottleneck; pruning keeps it manageable.
Only then think about the main instance — it rarely needs scaling, since it executes nothing.

The one-click version

If you'd rather not assemble this by hand: we packaged this exact architecture — main + worker on a single digest-pinned image, Redis, Postgres, pruning defaults, and S3 database backups wired in — as an open-source (MIT) Railway template:

Deploy: https://railway.com/deploy/n8n-production-stack-queue-mode
Source: https://github.com/Kjudeh/n8n-production-stack

Full disclosure: we (Bubbles Studio) built and maintain it — versions are bumped through weekly reviewed PRs and the stack is test-deployed from scratch before every update. Everything in this post applies to it 1:1, because it is this post's architecture.

Questions about queue mode or the template — comments are open, and so are issues on the repo.

DEV Community: Bubbles Studio

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

The architecture

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

Deployment failure modes to design around

The one-click version

Running n8n in production: queue mode, workers, and the settings that keep it alive

How queue mode works

The core configuration

The hardening most setups skip

Scaling checklist

The one-click version