# WhatsApp Chat Automation MVP for SMEs ## Complete 3-Month Project Plan (4 Sprints) --- ## PART 1: PRODUCT DEFINITION (Do This Before Sprint 1) ### 1.1 Who Exactly Is This For? Don't build for "all SMEs." Pick **one vertical** for the MVP. My recommendation, based on what actually converts: | Vertical | Why It Works | Primary Use Case | |---|---|---| | **Clinics / Salons / Dental** | High no-show cost, repetitive booking questions | Appointment booking + reminders | | **D2C / Retail stores** | High order-status query volume | Order tracking + catalog + COD confirmation | | **Real estate / Education** | Lead qualification is expensive | Lead capture + qualification + routing | **Pick ONE. I'll assume "Clinics & Salons + Local Services" for this plan** — smallest integration surface, fastest proof of ROI. ### 1.2 MVP Scope — The Ruthless Cut **IN SCOPE (v1)** 1. WhatsApp Business Cloud API onboarding (embedded signup) 2. Visual flow builder (drag-drop, max 15 node types) 3. FAQ bot with keyword + semantic matching (RAG on business docs) 4. Appointment booking flow with calendar slots 5. Human handover → shared team inbox 6. Broadcast/template campaigns with opt-out 7. Basic analytics dashboard 8. Multi-agent inbox (up to 3 agents) **OUT OF SCOPE (v1) — write this down and defend it** - ❌ Multi-channel (Instagram, Messenger, web widget) - ❌ Voice notes / image understanding - ❌ Deep CRM integrations (Salesforce, HubSpot) - ❌ Payments inside chat - ❌ Mobile app (mobile-responsive web only) - ❌ White-labelling / reseller portal - ❌ Multi-language beyond 2 languages - ❌ Advanced RBAC / audit logs ### 1.3 Success Metrics (define now, measure in Sprint 4) | Metric | Target | |---|---| | Time-to-first-automated-reply (signup → live bot) | < 30 minutes | | Bot containment rate (resolved without human) | ≥ 55% | | Message delivery success | ≥ 98% | | P95 bot response latency | < 3 seconds | | Design partners onboarded | 10 businesses | | Week-4 retention of design partners | ≥ 70% | --- ## PART 2: TECH ARCHITECTURE ### 2.1 Recommended Stack ``` ┌─────────────────────────────────────────────────────────┐ │ FRONTEND — Next.js 14 + TypeScript + Tailwind │ │ • React Flow (flow builder canvas) │ │ • TanStack Query, Zustand │ │ • Socket.io-client (live inbox) │ └─────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────┐ │ API LAYER — Node.js + NestJS (or FastAPI if Python) │ │ • REST + WebSocket gateway │ │ • JWT auth, tenant middleware │ └─────────────────────────────────────────────────────────┘ │ │ │ ┌──────────────────┐ ┌────────────────┐ ┌──────────────┐ │ WEBHOOK INGESTOR │ │ FLOW ENGINE │ │ AI SERVICE │ │ (thin, fast, │ │ (state machine │ │ (intent + │ │ ACK <200ms) │ │ executor) │ │ RAG + LLM) │ └──────────────────┘ └────────────────┘ └──────────────┘ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ QUEUE — BullMQ on Redis (inbound, outbound, campaigns) │ └─────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────┐ │ DATA │ │ • PostgreSQL (tenants, contacts, flows, messages) │ │ • Redis (session state, rate limits, cache) │ │ • pgvector (knowledge base embeddings) │ │ • S3/R2 (media) │ └─────────────────────────────────────────────────────────┘ INFRA: Docker → AWS ECS Fargate / Railway / Render OBSERVABILITY: Sentry + Grafana/Better Stack + structured logs ``` ### 2.2 Critical Architecture Decisions **a) Always queue inbound webhooks.** Meta retries aggressively and will disable your webhook if you're slow. Ingestor does: validate signature → dedupe by `message.id` → push to queue → return `200`. Nothing else. **b) Conversation state in Redis, not DB.** Key: `conv:{tenant_id}:{wa_id}` holding `{flow_id, current_node, variables, expires_at}`. TTL 24h. **c) Multi-tenancy = single DB with `tenant_id` on every table + Postgres Row Level Security.** Don't do DB-per-tenant at MVP. **d) Abstract the BSP behind an interface.** You may start with Meta Cloud API direct, but wrap it: ```typescript interface WhatsAppProvider { sendText(to: string, body: string): Promise sendTemplate(to: string, name: string, params: any[]): Promise sendInteractive(to: string, payload: InteractivePayload): Promise sendMedia(to: string, media: MediaPayload): Promise uploadMedia(file: Buffer): Promise } ``` Implement `MetaCloudProvider` first. Later you can add `TwilioProvider` / `GupshupProvider` without touching the flow engine. **e) Use Meta Cloud API directly for MVP** — free conversation tier, no BSP markup, full control. Cost: Meta's per-conversation pricing only. ### 2.3 Core Data Model (simplified) ```sql tenants(id, name, plan, wabas_id, phone_number_id, access_token_enc, created_at) users(id, tenant_id, email, role, password_hash) contacts(id, tenant_id, wa_id, name, attributes_jsonb, opt_in_status, last_seen_at) conversations(id, tenant_id, contact_id, status, assigned_user_id, window_expires_at) messages(id, tenant_id, conversation_id, direction, type, content_jsonb, wamid, status, error_code, created_at) flows(id, tenant_id, name, version, graph_jsonb, is_published) flow_sessions(id, tenant_id, contact_id, flow_id, current_node_id, vars_jsonb) kb_documents(id, tenant_id, source, title, content) kb_chunks(id, tenant_id, doc_id, content, embedding vector(1536)) templates(id, tenant_id, meta_template_name, category, status, body) campaigns(id, tenant_id, template_id, audience_filter_jsonb, status, stats_jsonb) appointments(id, tenant_id, contact_id, service, slot_start, slot_end, status) ``` --- ## PART 3: THE 4 SPRINTS **Sprint length:** 3 weeks each = 12 weeks. Week 13 = buffer/launch. **Team assumption:** 1 PM/you, 2 backend, 1 frontend, 1 full-stack/AI, 1 QA (part-time), 1 designer (part-time). --- ### 🟦 SPRINT 0 — Week 0 (Pre-Sprint, 5 days) Do NOT skip this. Meta approval is the #1 timeline killer. | Day | Task | |---|---| | 1 | Create Meta Business Account, verify business (upload docs — **this takes 2–10 days, start NOW**) | | 1 | Create Meta App, add WhatsApp product, get test number | | 2 | Repo setup, monorepo (Turborepo), CI (GitHub Actions), Docker Compose local env | | 2 | Provision Postgres, Redis, S3 bucket, staging environment | | 3 | Design system + Figma wireframes for 6 core screens | | 3 | Send test message via Cloud API with cURL — prove the pipe works | | 4 | Finalize DB schema, write migrations | | 4 | Recruit design partners — target 15 outreach → 10 committed | | 5 | Sprint 1 backlog groomed, story points estimated | **Sprint 0 Exit Criteria:** Test message sent + received via webhook. Business verification submitted. 10 design partners committed. --- ### 🟩 SPRINT 1 — Weeks 1–3 ## "Connect & Converse" **Goal:** A business can sign up, connect WhatsApp, and hold a two-way conversation with a human agent. #### Backend | # | Story | Pts | |---|---|---| | 1.1 | Auth: signup, login, JWT + refresh, password reset | 5 | | 1.2 | Tenant model + tenant-scoping middleware + Postgres RLS | 5 | | 1.3 | Meta Embedded Signup flow (OAuth) → store WABA ID, phone_number_id, encrypted token | 8 | | 1.4 | Webhook receiver: HMAC signature verify, dedupe, enqueue, 200 ACK <200ms | 8 | | 1.5 | `WhatsAppProvider` interface + `MetaCloudProvider` (text, media, interactive) | 8 | | 1.6 | Inbound worker: normalize payload → upsert contact → create/update conversation → persist message | 8 | | 1.7 | Outbound worker: send via provider, store `wamid`, handle rate limits + retry w/ backoff | 5 | | 1.8 | Status webhook handler: sent/delivered/read/failed → update message | 3 | | 1.9 | 24-hour customer service window tracking on conversation | 3 | | 1.10 | WebSocket gateway: push new messages to subscribed agents | 5 | | 1.11 | Media: download from Meta, upload to S3, signed URL serving | 5 | #### Frontend | # | Story | Pts | |---|---|---| | 1.12 | Auth screens + protected routing | 3 | | 1.13 | Onboarding wizard: connect WhatsApp (embedded signup), verify, success state | 8 | | 1.14 | **Team Inbox**: conversation list (unread, sorted), message thread, composer | 13 | | 1.15 | Real-time updates via socket, optimistic send, delivery ticks | 5 | | 1.16 | 24h window indicator + "session expired, use template" state | 3 | | 1.17 | Contact side-panel: name, phone, attributes, notes | 3 | **Sprint 1 Demo:** Sign up → connect WhatsApp → customer messages business number → appears in inbox live → agent replies → customer receives it. Media works both ways. **Sprint 1 Exit Criteria** - ✅ 99% inbound webhook processing success - ✅ Zero cross-tenant data leaks (verified by test) - ✅ Messages persisted with correct status transitions - ✅ Deployed to staging --- ### 🟨 SPRINT 2 — Weeks 4–6 ## "Automate" **Goal:** Business can build and publish an automated flow. Bot handles conversations and hands off to humans. #### Backend | # | Story | Pts | |---|---|---| | 2.1 | Flow schema (JSON graph): nodes, edges, validation with Zod | 5 | | 2.2 | **Flow Engine** — state machine executor with node handlers | 13 | | 2.3 | Node types: `send_message`, `ask_question` (with var capture + validation), `buttons`, `list`, `condition`, `delay`, `set_variable`, `http_request`, `assign_to_human`, `end` | 13 | | 2.4 | Trigger resolver: keyword match, first-message, "no flow → default flow" | 5 | | 2.5 | Session management in Redis, 24h TTL, resume/expire logic | 5 | | 2.6 | Handover protocol: bot pause on `assign_to_human`, agent takeover, "return to bot" | 8 | | 2.7 | Flow versioning: draft vs published, publish/rollback | 5 | | 2.8 | Flow test-runner API (simulate conversation without WhatsApp) | 5 | | 2.9 | Guardrails: max 1 flow per contact, loop detection, node execution cap | 3 | #### Frontend | # | Story | Pts | |---|---|---| | 2.10 | **Flow Builder canvas** (React Flow): add/connect/delete nodes, pan/zoom, auto-layout | 13 | | 2.11 | Node config panels for each node type | 13 | | 2.12 | Variable picker (`{{contact.name}}`, `{{answers.email}}`) | 5 | | 2.13 | Flow list, duplicate, publish button + validation errors surfaced | 5 | | 2.14 | **Test-in-browser simulator** (side drawer chat preview) | 8 | | 2.15 | Inbox: bot/human badge, "Take over" button, assignment dropdown | 5 | #### Templates (accelerate onboarding) | # | Story | Pts | |---|---|---| | 2.16 | 3 prebuilt flow templates: Welcome+Menu, Lead Capture, FAQ Menu | 5 | **Sprint 2 Demo:** Build a flow visually → test in simulator → publish → real WhatsApp customer goes through button menu, answers questions, gets routed to agent. Agent takes over mid-conversation. **Sprint 2 Exit Criteria** - ✅ All 10 node types working E2E - ✅ P95 flow-step latency < 1.5s - ✅ Handover works without message loss - ✅ 3 design partners have a live published flow --- ### 🟧 SPRINT 3 — Weeks 7–9 ## "Intelligence + Outbound" **Goal:** AI answers unscripted questions from business knowledge. Business can book appointments and run campaigns. #### AI / Backend | # | Story | Pts | |---|---|---| | 3.1 | Knowledge base ingestion: paste text, upload PDF/DOCX, URL scrape | 8 | | 3.2 | Chunking + embeddings (OpenAI `text-embedding-3-small`) → pgvector | 5 | | 3.3 | Retrieval: hybrid search (vector + Postgres full-text BM25), rerank top-5 | 8 | | 3.4 | **AI Answer node**: RAG prompt, grounded answer, cite nothing-found → fallback | 8 | | 3.5 | Intent classification: route to flow vs AI vs human (few-shot LLM or fine-tuned classifier) | 8 | | 3.6 | Hallucination guardrails: confidence threshold, "I'll connect you to our team" fallback, forbidden-topic filter | 5 | | 3.7 | LLM cost controls: per-tenant token budget, response caching, prompt compression | 5 | | 3.8 | Streaming disabled / chunked sends — split long answers into ≤2 messages | 3 | #### Appointments | # | Story | Pts | |---|---|---| | 3.9 | Business hours + services + slot-duration config | 5 | | 3.10 | Slot generation + availability check (no double-booking, DB constraint) | 8 | | 3.11 | `booking` node: show slots as WhatsApp list → confirm → persist | 8 | | 3.12 | Google Calendar 2-way sync (optional, timebox 2 days) | 8 | | 3.13 | Reminder scheduler: T-24h and T-2h template messages via BullMQ delayed jobs | 5 | | 3.14 | Reschedule / cancel via chat | 5 | #### Outbound / Campaigns | # | Story | Pts | |---|---|---| | 3.15 | Template management: create → submit to Meta API → poll approval status | 8 | | 3.16 | Contact import (CSV) with opt-in consent field, dedupe by phone | 5 | | 3.17 | Segments: filter by attributes/tags/last-seen | 5 | | 3.18 | Campaign sender: batched queue, throttle to tier limit, per-message status tracking | 8 | | 3.19 | Opt-out handling: STOP keyword → set `opt_out`, exclude from all campaigns | 3 | #### Frontend | # | Story | Pts | |---|---|---| | 3.20 | Knowledge base UI: sources list, add/delete, "test a question" playground | 8 | | 3.21 | AI settings: tone, fallback message, confidence slider | 3 | | 3.22 | Appointment calendar view + manual booking | 8 | | 3.23 | Template builder UI with live WhatsApp preview + variable mapping | 8 | | 3.24 | Campaign wizard: audience → template → schedule → review → send | 8 | | 3.25 | Contacts table: search, filter, tags, import | 5 | **Sprint 3 Demo:** Upload clinic's service PDF → customer asks "do you do teeth whitening and how much?" → AI answers from doc → customer books a slot → gets confirmation → 24h reminder fires. Separately, business sends a promo campaign to 200 opted-in contacts. **Sprint 3 Exit Criteria** - ✅ RAG accuracy ≥ 80% on 50-question eval set per design partner - ✅ Zero double-bookings under concurrent load test - ✅ Campaign of 500 messages sends with ≥98% delivery - ✅ LLM cost < $0.03 per resolved conversation --- ### 🟥 SPRINT 4 — Weeks 10–12 ## "Measure, Harden, Launch" **Goal:** Production-ready, billable, observable. 10 paying/design partners live. #### Analytics | # | Story | Pts | |---|---|---| | 4.1 | Event tracking table + aggregation jobs (hourly rollups) | 8 | | 4.2 | Dashboard: conversations, new contacts, bot containment %, avg first-response time, top intents, unanswered questions | 13 | | 4.3 | Campaign report: sent/delivered/read/replied/failed + failure reason breakdown | 5 | | 4.4 | "Unanswered questions" list → one-click "Add to knowledge base" | 5 | | 4.5 | CSV export | 3 | #### Billing & Plans | # | Story | Pts | |---|---|---| | 4.6 | Stripe/Razorpay integration: 3 plans, subscription lifecycle, webhooks | 8 | | 4.7 | Usage metering: conversations/month, AI messages, contacts | 5 | | 4.8 | Plan limits enforcement + upgrade prompts + 14-day trial | 5 | #### Hardening | # | Story | Pts | |---|---|---| | 4.9 | Rate limiting (per-tenant, per-IP), input sanitization, OWASP pass | 5 | | 4.10 | Token encryption at rest (KMS), secrets rotation, PII redaction in logs | 5 | | 4.11 | Dead-letter queue + admin retry UI + alerting on DLQ depth | 5 | | 4.12 | Load test: 500 concurrent conversations, 50 msg/sec sustained | 5 | | 4.13 | Observability: Sentry, uptime monitors, dashboards, on-call runbook | 5 | | 4.14 | Backups (daily PITR), disaster recovery drill | 3 | | 4.15 | GDPR/DPDP: data export, delete-my-data, DPA, privacy policy, cookie consent | 5 | | 4.16 | Bug bash + fix top 20 issues | 8 | #### Launch | # | Story | Pts | |---|---|---| | 4.17 | Onboarding checklist + product tour + empty states | 5 | | 4.18 | Help center: 12 articles + 5 Loom videos | 5 | | 4.19 | Marketing site + pricing page + demo booking | 8 | | 4.20 | Support: shared inbox, SLA, feedback widget in-app | 3 | **Sprint 4 Demo:** Full journey — marketing site → trial signup → 20-min guided onboarding → live bot → dashboard showing real ROI → upgrade to paid. **Sprint 4 Exit Criteria** - ✅ 10 design partners live in production - ✅ Bot containment ≥ 55% aggregate - ✅ 99.5% uptime over final 2 weeks - ✅ First 3 paid conversions - ✅ NPS ≥ 30 from design partners --- ## PART 4: STEP-BY-STEP EXECUTION GUIDE ### Step 1: Meta Setup (Day 1 — do this first, always) 1. `business.facebook.com` → create Business Portfolio 2. Settings → Business Info → **Start Verification** (upload incorporation cert, utility bill, bank statement). ⏳ 2–10 days 3. `developers.facebook.com` → Create App → type **Business** 4. Add Product → **WhatsApp** → generates test number + temp token 5. Copy `Phone Number ID`, `WABA ID`, `App Secret` 6. Test immediately: ```bash curl -X POST "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages" \ -H "Authorization: Bearer {TOKEN}" \ -H "Content-Type: application/json" \ -d '{"messaging_product":"whatsapp","to":"91XXXXXXXXXX", "type":"template","template":{"name":"hello_world","language":{"code":"en_US"}}}' ``` 7. Set up webhook: deploy an ngrok/staging endpoint, subscribe to `messages` field, verify token handshake. ### Step 2: Repo & Environments (Day 2) ``` whatsapp-automation/ ├── apps/ │ ├── web/ # Next.js dashboard │ ├── api/ # NestJS REST + WS │ ├── webhook/ # ultra-thin ingestor │ └── worker/ # BullMQ processors ├── packages/ │ ├── db/ # Prisma schema + migrations │ ├── flow-engine/ # framework-agnostic executor │ ├── wa-provider/ # provider abstraction │ └── shared/ # types, zod schemas, utils └── docker-compose.yml # postgres, redis, minio ``` Environments: `local` → `staging` → `production`. Never test on production WABA. ### Step 3: Build Order Within Each Sprint Always this sequence — it prevents rework: ``` 1. DB migration 2. Zod/TS types in packages/shared 3. Service layer + unit tests 4. API endpoint + integration test 5. Frontend hook (TanStack Query) 6. UI component 7. E2E test (Playwright) 8. Deploy to staging → design partner tests ``` ### Step 4: Flow Engine Implementation Pattern ```typescript // The core loop — keep it this simple async function executeFlow(session: Session, input: InboundMessage) { let node = getNode(session.flowId, session.currentNodeId); let steps = 0; while (node && steps++ < MAX_STEPS) { const handler = nodeHandlers[node.type]; const result = await handler.execute({ node, session, input }); session.vars = { ...session.vars, ...result.vars }; if (result.action === 'WAIT_FOR_INPUT') { session.currentNodeId = node.id; await saveSession(session); return; // pause, await next message } if (result.action === 'HANDOFF') { await assignToHuman(session); await clearSession(session); return; } if (result.action === 'END') { await clearSession(session); return; } node = getNode(session.flowId, result.nextNodeId); input = null; // input consumed } } ``` ### Step 5: RAG Pipeline Recipe ``` Ingest: extract text → clean → chunk (500 tokens, 50 overlap) → embed → store in pgvector with tenant_id Query: user question → embed question → vector search top 20 (filtered by tenant_id) → BM25 full-text top 20 → reciprocal rank fusion → top 5 → prompt: "Answer ONLY from CONTEXT. If not in context, reply exactly: NEED_HUMAN. Keep under 60 words. Tone: {{tenant.tone}}. CONTEXT: {{chunks}} QUESTION: {{q}}" → if response == NEED_HUMAN → handover node → else send + log for eval ``` ### Step 6: Design Partner Loop (run weekly, every sprint) ``` Mon — Deploy to staging Tue — 3× 30-min partner sessions (watch them use it, don't explain) Wed — Synthesize feedback → tag as [must-fix / next-sprint / no] Thu — Groom backlog, adjust sprint Fri — Ship to production, send changelog ``` ### Step 7: Pre-Launch Checklist (Week 12) ``` ☐ Business verification approved ☐ Display name approved, phone number quality = GREEN ☐ Messaging tier ≥ 1,000/24h ☐ ≥3 templates approved (utility + marketing) ☐ Webhook success rate >99% for 7 days ☐ Zero P0/P1 bugs open ☐ Backups verified by actual restore ☐ Runbook: webhook down, token expired, queue backlog, Meta outage ☐ Terms, Privacy, DPA published ☐ Stripe/Razorpay live mode tested with real card ☐ Support email + in-app widget live ``` --- ## PART 5: RISK REGISTER | Risk | Impact | Mitigation | |---|---|---| | **Meta business verification delayed** | Blocks everything | Start Day 1. Keep test number for dev. Have a BSP (Gupshup/360dialog) as backup path. | | **Template rejections** | Campaigns blocked | Study Meta's policy doc, submit 5 variants early in Sprint 3, avoid promotional language in utility templates. | | **Low messaging tier** | Can't send campaigns | Warm up gradually, maintain quality rating, request tier increase. | | **LLM hallucination** | Trust destroyed | Strict grounding prompt, confidence threshold, `NEED_HUMAN` escape, log every AI reply for review. | | **LLM cost blowout** | Unit economics break | Cache, use `gpt-4o-mini`/Haiku, cap tokens, per-tenant budget, prefer flows over AI where possible. | | **Flow builder UX too complex** | Onboarding fails | Ship 3 templates. "Time to first live bot < 30 min" is a hard gate. | | **Scope creep from partners** | Miss 3-month deadline | Feature freeze at Week 10. Parking lot document. PM says no. | | **24h window confusion** | Failed sends, angry users | Explicit UI state + auto-suggest template when window closed. | | **Single dev bottleneck on flow engine** | Sprint 2 slips | Pair on the engine; keep node handlers as independent plug-ins others can write. | --- ## PART 6: MVP PRICING (validate in Sprint 4) | Plan | Price/mo | Includes | |---|---|---| | **Starter** | $29 | 1,000 conversations, 1 agent, 500 AI msgs, 3 flows | | **Growth** | $79 | 5,000 conversations, 3 agents, 3,000 AI msgs, unlimited flows, campaigns | | **Pro** | $199 | 20,000 conversations, 10 agents, 15,000 AI msgs, API access, priority support | *Meta conversation charges passed through at cost + 10%.* --- ## PART 7: TEAM & EFFORT SUMMARY | Sprint | Story Points | Focus | Key Deliverable | |---|---|---|---| | 0 | ~15 | Setup | Test message flowing, partners recruited | | 1 | ~79 | Plumbing | Two-way inbox on real WhatsApp | | 2 | ~113 | Automation | Visual flow builder + bot + handover | | 3 | ~145 | Intelligence | RAG AI + bookings + campaigns | | 4 | ~124 | Production | Analytics, billing, hardened, launched | **Velocity assumption:** ~40 pts/week with 5 devs. If your team is smaller, cut Sprint 3's Google Calendar sync, campaign scheduling, and multi-agent (go single-agent) — that's ~35 points saved. --- ## The Three Things That Will Actually Decide Success 1. **Start Meta verification on Day 1.** Everything downstream depends on it. I've seen teams lose 3 weeks here. 2. **Time-to-first-live-bot under 30 minutes.** SME owners aren't patient. Prebuilt templates are not a nice-to-have — they're the product. 3. **Ship to 10 real businesses by Week 6, not Week 12.** Sprint 2's output is enough to be genuinely useful. Real usage data through Sprints 3–4 is worth more than any amount of internal planning. Want me to go deeper on any piece — the flow builder JSON schema, the RAG evaluation harness, the Meta embedded signup implementation, or a scaled-down version for a 2-person team?

act as AI chatbot expert with 5 years of experience ,i want ...