Wakeelوكيل
An AI employee that answers a business's customers on WhatsApp, Instagram and Messenger — in their own Arabic dialect.
- Status
- Phases 0–8 implemented and verified locally; real-number channel run and production deploy pending.
- Period
- 2026
- Platforms
- Web · WhatsApp · Instagram · Messenger
- Repository
- Private — available on request
- Live
- —

01Overview
A multi-tenant SaaS: a business connects its messaging channels, and an AI employee answers 24/7 in text and voice notes, sends product photos, captures confirmed leads and hands conversations to humans. Teams work from a premium Arabic RTL dashboard.
By the numbers
- commits
- 121
- commits
- git history
- delivery phases
- 9
- delivery phases
- docs/BACKLOG.md
- Arab countries & dialects
- 22
- Arab countries & dialects
- README
- verified screens
- 65
- verified screens
- docs/screens
02The problem
Small and medium businesses in the Arab world sell through chat. Customers write at midnight, in dialect, often by voice note — and the business owner is the only one answering. Leads go cold, questions repeat, and generic chatbots answer in stiff formal Arabic or invent answers.
03The vision
An employee that never sleeps, never forgets and never makes things up: it answers only from what the business taught it, in the customer's dialect, and steps aside when a human should take over.
04The solution
Webhooks from Meta are verified, stored and acknowledged instantly, then processed by an idempotent worker pipeline. A LangGraph agent routes, retrieves from a per-tenant hybrid search index, calls tools (products, images, lead fields, hand-off) and replies — as text, or as a voice note in the customer's dialect.
05Key features
- 01
Grounded answers with citations
Hybrid search (pgvector + Arabic full-text, fused with RRF) over uploaded PDFs, Word, Excel, web pages, FAQs and products. Every reply shows its sources in the inbox; unanswered questions become one-click FAQ entries.
- 02
Leads confirmed in code, not by the model
The employee reads the customer's name and phone back in their dialect; the confirmation is classified in code, so a lead exists only after the customer said yes to those exact details. Kanban, table, CSV export and email/web-push alerts follow.
- 03
Voice notes both ways
Incoming voice notes are transcribed and answered; replies can be voice notes in the agent's dialect and chosen voice, encoded as Ogg/Opus — the format WhatsApp expects — without ffmpeg.
- 04
Any business, any Arab country
Workspace type (store, clinic, restaurant, real estate…) and country set the persona, currency, time zone and dialect across all 22 Arab countries.
- 05
Live inbox with take-over
Realtime inbox over SSE; a human can take any conversation over and hand it back. A built-in customer simulator lets a business test its employee before going live.
- 06
Plans, usage and billing
Usage metered per tenant and month (tokens, speech seconds, TTS characters), plans, billing screens and an internal admin console.
06Screens
07System architecture
- L1Channels
- WhatsApp Cloud API
- Messenger
- Web simulator
- L2Web
- Next.js App Router
- next-intl (ar / en)
- SSE inbox
- RTL design system
- L3API
- FastAPI
- JWT + rotating refresh
- RBAC
- Signed webhooks
- L4Worker
- ARQ on Redis
- Per-conversation lock
- LangGraph agent
- Retries → dead-letter
- L5Data
- PostgreSQL 16
- pgvector
- Row-level security
- MinIO / S3
- L6Providers
- LLM
- Speech-to-text
- Text-to-speech
- Embeddings
08Engineering decisions
Tenant isolation in the database, not only in code
PostgreSQL row-level security is forced on tenant tables, with isolation tests. Webhooks reach their tenant through a SECURITY DEFINER function that returns only ids, so RLS never has to be bypassed.
Idempotent by construction
Raw payloads are stored before processing; provider message ids are unique per channel so duplicate deliveries are no-ops; a Redis lock per conversation prevents double replies; failures retry with backoff and then dead-letter.
Provider interfaces with honest fallbacks
Without an API key the employee politely hands every conversation to the team; a deterministic 'scripted' provider exists for demos and CI and is refused in production.
09Technical challenges
Stopping the model from inventing leads
A language model can 'hear' a confirmation that never happened. The lead flow keeps a draft on the conversation; the customer's next message is classified in code as yes / no / unclear, and only a yes creates the lead — the draft id becomes the lead id, so a retried job can never create a second one.
Arabic retrieval
Vector search alone misses exact product names and prices; keyword search alone misses dialect phrasing. Combining pgvector with Arabic full-text search through reciprocal rank fusion gave precise, citable passages.
10Lessons learned
Let the model write; let code decide anything that has consequences.
A webhook pipeline is only as reliable as its replay story.
My contribution
Product definition, architecture, backend, agent design, the Arabic-first dashboard and the phase-by-phase delivery documented in the repository (121 commits).
Technology
- Python
- FastAPI
- SQLAlchemy
- PostgreSQL
- pgvector
- Redis
- ARQ
- LangGraph
- OpenAI
- Next.js
- TypeScript
- Tailwind CSS
- next-intl
- Docker
- GitHub Actions
- RAG
How this was verified
Source, architecture and backlog reviewed. Screens are the project's own captures of the running app, saved per delivery phase in docs/screens.
Related projects
- W
WaCRM
- TanStack Start
- React
- TypeScript
- Supabase
- PostgreSQL
WaCRM
An early WhatsApp CRM for merchants — the seed of Wakeel.
FoundationWebSaaS 
NOVA
A voice-first personal AI operating system — where a permission layer, not the model, decides what may run.
In developmentAndroidAIDesktop
Sanad
سندEvery skill has value — a bilingual platform connecting talent with jobs, freelance work and volunteering.
LiveWeb
Next project
NUR