WhatsApp Commerce Copilot

Problem

Pakistani clothing brands sell through Instagram and WhatsApp DMs, and lose orders in two places: questions that go unanswered while the owner is asleep or busy, and Cash-on-Delivery orders that were never properly confirmed.

Before writing code, the squad validated the problem on the ground — messaging 16 Pakistani clothing brands as real customers within one hour to measure how many DMs went unanswered. Only 1 of the 16 replied instantly and completely. The squad then interviewed brand owners to shape the product.

On the 30–35% figure. The squad's problem statement estimated that 30–35% of Cash-on-Delivery orders come back undelivered because customers were never confirmed before dispatch. That range is the squad's own working assumption from customer-discovery conversations — it is recorded in the squad repository without a source, and no authoritative published statistic was found to support that specific range. Treat it as a project assumption, not a measured industry rate.

Solution

An agentic copilot that sits on the brand's WhatsApp number and answers customers from the store's real catalogue rather than from open-ended model knowledge.

• AI auto-replies — answers customers browsing the catalogue automatically.
• Human Mode — a one-click toggle that disables the AI so the owner can reply personally.
• Stock management — product stock is tracked and edited from the dashboard.
• Live syncing — conversations and stock updates propagate in real time.

The copilot reads customer questions in English, Roman Urdu and Urdu script — language detection is a purpose-built keyword heuristic, because langdetect does not handle Roman Urdu — and answers on sizing, delivery and COD confirmation. The shipped transport is WhatsApp only; Instagram was part of the original product vision but no Instagram integration exists in the codebase.

Architecture

The whole backend runs from a single docker compose up: database, Redis, the Evolution API WhatsApp gateway and the Python backend all come up together. The dashboard is a separate React app.

Dashboard

React / Vite app on port 5173 — conversations, stock, and the Human Mode toggle.

Backend

Python / FastAPI service on port 8000 — all business logic, catalogue retrieval and AI orchestration.

Gateway adapter

A separate Node.js / Express service on port 3001 that normalises Evolution API webhooks and posts them to the backend over an internal token-authenticated route. It is transport-only, which is what makes a later swap to the official Meta Cloud API a contained change.

WhatsApp protocol engine

Self-hosted Evolution API on port 8080; the brand's number is linked by scanning a QR code from the dashboard.

Data stores

PostgreSQL as the primary store (12 tables, SQLite for tests); Redis as the cache Evolution API requires.

Infrastructure

Docker Compose orchestrating PostgreSQL, Redis, Evolution API, the backend and the gateway.

How the AI layer is grounded

The backend ships with a deterministic catalogue pipeline that keeps working with no AI key present. When a provider is configured, inbound messages pass through a LangChain intent chain, and LangChain response generation is used for ambiguous or low-confidence queries only. Crucially, that generation step receives only store-scoped products and policies retrieved by the backend — retrieval grounding that keeps answers tied to the brand's actual inventory instead of invented detail.

The grounding contract is enforced, not merely prompted: the model never queries the database. The deterministic layer pre-fetches at most five candidates, and any product or variant ID the model returns outside that closed set is rejected in favour of the deterministic response. Every reply carries traceability fields (matched_product_id, sources). Store isolation is likewise structural — every query is scoped by store_id.

Technology

• Python
• FastAPI
• React
• LangChain
• Redis
• Docker Compose
• Evolution API
• Agentic AI

Results and validation

• Built in Comebck Pakistan Cohort 1 — described by its organisers as an 8-week AI readiness program, run in four-person squads with 50 places in the founding cohort.
• Top 5 of the cohort. This placement is recorded on Sajid's résumé; no public cohort results page was found to link to, so it is stated here as a self-reported outcome.
• Problem validated with primary research before building: 16 brands contacted within one hour (1 replied instantly and completely), followed by interviews with brand owners.
• Delivered as a working, fully containerised system that runs on a fresh machine in three documented steps, with a backend pytest suite covering the catalogue, grounding and order flows.

Team and my contribution

Built by a four-person squad — Squad Margalla: Sajid Islam, Khansa Maryam, Muhammad Ullah Baig and Manahil Shah — over eight weeks. My résumé records my part as running the ground-truth user validation (contacting the 16 brands and interviewing owners) and building the agentic AI and LLM integration; the squad repository's commit history shows my work concentrated in the backend, the catalogue and grounding pipeline, and the order flows.

The precise engineering split across the four squad members is not documented in the public repository, so it is deliberately not itemised here.

Limitations and lessons learned

• The LLM layer is optional: without an API key the system falls back to the deterministic catalogue pipeline. That was a deliberate reliability choice, but it means the richest behaviour depends on a configured provider.
• Generation is intentionally restricted to ambiguous or low-confidence queries. It narrows what the AI can do, and in exchange it sharply narrows what it can get wrong.
• There is no public hosted demo — the project runs locally via Docker, so evaluation requires cloning the repository.
• The WhatsApp transport is Evolution API, which is Baileys-based and therefore unofficial. The project's own security notes are explicit that this may conflict with WhatsApp's terms and that the protocol can change without warning. The gateway adapter exists precisely so the official Meta Cloud API can replace it without touching the backend.
• It is an MVP, and documented as one: the dashboard has no real authentication, voice messages are designed but not implemented, and Roman Urdu detection is heuristic rather than a trained model.
• The clearest lesson: grounding beats fluency. Restricting the model to store-scoped products and policies mattered more to answer quality than any prompt wording.

Related reading

• How the catalogue-grounded reply pipeline works — the retrieval-first design, and the candidate-set check that makes grounding enforced rather than requested. Draft.
• Why Human Mode is a database column — modelling AI-versus-human ownership so a handoff survives restarts and concurrent messages. Draft.
• Entropy-Aware Data Preservation System — the earlier project where putting rules where they cannot be bypassed first paid off.