Building a WhatsApp Business AI Assistant for Real Estate: An Architecture Overview

Canonical note: this is a technical companion to Sabbaq. No credentials, keys or internal endpoints are included.

Sabbaq is a WhatsApp-first lead desk for Dubai real estate brokerages. The product promise is simple:

Every Property Finder and Bayut lead answered in seconds, in Arabic or English, on your existing WhatsApp number. Median under 5 minutes, or your month back.

Putting money behind a reply-time number forces some interesting engineering decisions. This post walks through the architecture at a high level: ingestion, the conversation engine, guardrails, human handoff, tenancy and metrics.

The constraints

• Channel: the WhatsApp Business Platform (Cloud API) on the customer's own WhatsApp Business account. The brokerage keeps its number in its own Meta account and can revoke access at any time.
• Languages: English and Gulf Arabic, often mixed in one chat.
• Latency: first reply in seconds; the business metric is the median time to first reply from lead arrival.
• Safety: the assistant must never invent a price, give legal or mortgage advice, or negotiate.
• Multi-tenant: many brokerages, strictly separated data.
• No portal API: we don't pull from portal APIs. Leads come in through channels the brokerage already controls.

1. Ingestion: two lead sources

 WhatsApp Cloud API webhook ──┐
                              ├──► Lead normaliser ──► Conversation engine
 Inbound lead email (parsed) ─┘

WhatsApp. Any inbound message to the connected number becomes (or updates) a lead. The webhook handler verifies the Meta signature, de-duplicates on message ID (Meta retries), persists the raw event, and enqueues work, returning 200 fast. Keep webhook handlers thin; do the slow work async.

One honest limitation: a plain WhatsApp message doesn't tell you which portal the lead came from.

Email. Portals send lead notification emails. Each workspace gets a unique inbound address; brokerages forward Property Finder, Bayut and Dubizzle lead emails there. A parser per portal extracts name, phone, listing reference and message, tags the lead with its portal, and triggers a WhatsApp intro using a Meta-approved template (business-initiated messages outside the 24-hour window need templates).

2. The conversation engine

Each inbound message runs through a pipeline:

1. Load context: workspace settings, the lead's history, the brokerage's listings and knowledge base.
2. Language detection: reply in the lead's language.
3. Guardrail pre-check: classify for handoff topics before generating anything (see §3).
4. Generate: an LLM call grounded in retrieved listings and knowledge only.
5. Guardrail post-check: validate the draft against the source data.
6. Act: send live, or store as a draft in shadow mode.

Qualification is deliberately one question at a time: buy or rent, budget, area, bedrooms, timing, cash or mortgage. Each answer is written to structured lead fields, not just left in the transcript, so routing and reporting can use it.

The very first message discloses that it's an AI assistant. That's a product decision and good practice under Meta's policies. We position it as the brokerage's own assistant for its own leads, not a general-purpose bot.

3. Guardrails: trust nothing the model says about facts

The biggest risk in real estate is a confident wrong number. Our rules:

• Grounding check. Any fact in a draft (price, size, availability) must match the listings or knowledge base. Prices must fall within a tight tolerance (2%) of the source. If they don't, the draft is replaced with "I'll check with the agent."
• Fixed-reply handoffs (in English and Gulf Arabic) for: price negotiation and discounts; legal topics (contracts, SPA, title deed, POA); mortgage advice; explicit human requests ("AGENT", «وكيل»); viewing confirmation; and ID or card numbers, where the lead is told not to send them.
• Output filters. Do-not-say phrases and fabricated links are blocked.
• Alerts. Complaints, scam-like wording and very high budgets notify the manager.
• Consent. STOP / «إيقاف» and START / «ابدأ» are handled automatically and logged. Manual sends are blocked after an opt-out or outside the 24-hour window.

The lesson: treat the LLM as a draft writer, and put deterministic checks on both sides of it.

4. Shadow mode as a first-class state

Every workspace starts in shadow mode: the engine runs end to end, but output lands as a draft that an agent approves (with inline edits) or discards. This was the single best decision we made:

• Owners see real answers to real leads before anything is sent.
• Edits are a signal for gaps in the knowledge base.
• It's the safe fallback: when a trial ends, the workspace drops back to shadow mode and data is kept.

Implementation-wise, "send" is a strategy chosen per workspace and per chat. A take-over/hand-back toggle pauses the assistant for a single conversation when an agent steps in.

5. Handoff and the SLA alarm

When a conversation needs a human, it's routed with a summary by area, language or listing. Handing off moves the latency risk from the model to people, so:

• Each handed-off lead gets a countdown in the inbox.
• If no one acknowledges it in time (default 5 minutes), the manager gets a WhatsApp alert and the lead is auto-reassigned (area, language, then round-robin).
• The alarm fires once per unacknowledged lead to avoid alert fatigue.

6. Multi-tenancy

Each brokerage is a workspace. The workspace is bound in a signed session, membership is rechecked on every request, and the query layer refuses tenant-table queries without a workspace scope. Tests cover the isolation. In short: each brokerage's data is logically separated by workspace and enforced on every request.

Roles are layered: Agent (inbox, replies, approvals, viewings), Admin (plus settings, listings, knowledge, metrics), and Owner (plus billing, WhatsApp connection and users).

7. Integrations

An outbound, signed webhook POSTs on events like lead qualified and viewing confirmed, so brokerages can push into any CRM. Lead and consent CSV exports are self-serve.

8. Metrics: measuring the promise

The metric we guarantee is the median time to first reply from lead arrival, whoever replies (assistant or agent). Median beats mean: one stuck chat can't hide behind fast ones, and one fast reply can't flatter a bad week.

The weekly report (Monday to Sunday, Dubai time) covers leads, after-hours leads, replied, median first reply, replies under 5 minutes, qualified, viewings requested and confirmed, handoffs, opt-outs and leaked leads. Owners and admins see the median view on every plan.

9. Bilingual UI details

Arabic support isn't just the model. The agent inbox renders direction per message bubble, and numbers, prices and listing references are isolated so they don't flip inside right-to-left text. Small thing, huge difference for agents.

Takeaways

• Keep webhooks thin and idempotent; process async.
• Ground every fact, and put deterministic checks before and after the model.
• Make "draft, don't send" a first-class mode, not a debug flag.
• Put timers on human handoffs, because that's where latency hides.
• Pick one honest metric and build the product around it.

If you're running a brokerage in Dubai, or you're just curious how it behaves on real leads, see Sabbaq at getsabbaq.com.