Plumber WhatsApp Agent - WhatsApp Booking Agent for Solo Plumbers

Project Overview & Problem Statement

Challenge: Solo plumbers like Jamal lose 2-3 jobs per week because they can't reply to WhatsApp messages while working on-site. By the time they check their phone, customers have already texted another plumber. WhatsApp Business auto-reply sends one canned message and stops — it can't scope the problem, quote a price, or book a time slot.

Solution: An AI agent named Jamal that sits on WhatsApp and handles customer inquiries end-to-end in bahasa santai — greeting, scoping the problem, quoting a fixed price, booking an available time slot from a real schedule, and closing the conversation with a thank you. The customer thinks they're texting the real plumber.

Key Benefits

Zero Missed Leads: Every WhatsApp message gets an instant, intelligent reply — even while the plumber is under a sink
Natural Conversation: Agent speaks bahasa santai (casual Malay-English mix), indistinguishable from a real tradesman texting
Fixed-Price Quoting: Confident, single-price quotes with clear inclusions — no "lebih kurang" or "tengok keadaan"
Schedule-Aware Booking: Reads a real 7-day schedule, offers only free slots, handles multi-hour jobs, prevents double-booking
Guided 5-Step Flow: Every conversation follows a structured path: greet, scope, quote, book, close — no off-topic drift

Application Features

Step 1: Inquiry Handler

Greets the customer warmly, confirms they're in the service area (PJ, Subang, Shah Alam), and asks what the plumbing problem is. Politely declines customers outside the coverage area.

Step 2: Problem Scoping

Asks follow-up questions — where exactly is the issue, is it urgent, and requests a photo if the problem description is unclear. Does not quote a price until the problem is understood.

Step 3: Fixed-Price Quoting

Matches the problem to a service type and quotes a single fixed price with what's included and how long it takes. No ranges, no negotiation.

Step 4: Schedule-Aware Booking

Checks a pre-loaded 7-day schedule with existing bookings. Offers 2-3 available time slots, handles multi-hour jobs requiring consecutive slots, and prevents double-booking.

Step 5: Close & Thank

Ends every conversation with a thank you — whether the customer books or not. Confirmed bookings get a summary with job, date, time, address, and price.

Plumbing-Only Guardrails

Agent strictly handles plumbing topics only. Off-topic messages (relationship advice, cooking tips, politics) get a friendly redirect: "Saya tukang paip je boss!"

Services Covered (10 Job Types)

Paip BocorRM200 | 2 hrs

Sinki TersumbatRM120 | 1 hr

Tukar TapRM100 | 1 hr

Tandas RosakRM150 | 1 hr

Tandas Rosak TerukRM280 | 2 hrs

Water HeaterRM300 | 2 hrs

Pasang SinkiRM250 | 2 hrs

Paip PecahRM350 | 2-3 hrs

Water PumpRM300 | 2 hrs

Renovation PlumbingRM600 | 3 hrs

AI Integration & Intelligence

Bahasa Santai Persona

The AI agent speaks like a real Malaysian plumber — casual, friendly, mixing Malay and English naturally. Uses "saya" and "awak", keeps messages under 4 sentences. Never reveals it's AI.

Strict Conversation Flow

System prompt enforces a 5-step flow in order: greet, scope, quote, book, close. The agent cannot skip steps, cannot quote before understanding the problem, and always ends with a thank you.

Schedule-Grounded Booking

The full 7-day schedule (with existing bookings and free slots) is injected into the system prompt. The LLM reasons about slot availability, consecutive-slot requirements, and conflicts in natural language.

4-5x Token Efficiency

This agent uses ~1,000 tokens per turn — only service config, conversation history, and schedule sent to the LLM. General-purpose agent frameworks (OpenClaw, n8n agents) use ~5,000 tokens/turn for the same task, adding bootstrap files, identity context, and tool schemas as dead weight.

Technical Architecture & Implementation

Frontend Stack

HTML5 CSS3 Vanilla JavaScript Poppins Font

AI Stack

Google Gemini 2.0 Flash BYO API Key (Client-Side) System Prompt Engineering

Deployment

GitHub Pages Static HTML (No Backend) Embedded Schedule Data

System Architecture

Zero-Backend Design: Everything runs client-side — the HTML page calls the Gemini API directly from the browser using the visitor's own API key
Embedded Schedule: The 7-day booking schedule (23 existing bookings, 49% occupancy) is embedded directly in the HTML as a JavaScript object — no fetch() calls, works on file:// and https://
System Prompt as Config: Services, prices, schedule, and conversation rules are all injected into a single system prompt. No tool calls, no function calling — pure prompt engineering
Conversation History Management: Last 20 turns kept in memory; older turns pruned to stay within token budget

Production Deployment Notes

This demo runs entirely in the browser with a BYO Gemini API key. In a real WhatsApp deployment, the following additions would be needed:

Required for Production

WhatsApp Business API: Via Twilio or Meta direct — receives and sends real WhatsApp messages programmatically
LLM API (Server-Side): Gemini or Claude API called from a backend server, not client-side — the API key is held securely on the server
Backend Server: Flask/FastAPI on Cloud Run — receives WhatsApp webhook, calls LLM, sends reply back through WhatsApp API

Session Management

Session Timeout: If no reply in 24 hours, Jamal sends one follow-up ("Hi, masih nak book tak?"), then closes the conversation
Conversation Persistence: Stored in a database (SQLite or Firestore), so a customer can WhatsApp back 3 days later and Jamal remembers the full context
Multi-Customer: Each phone number gets its own conversation thread — multiple customers can chat with Jamal simultaneously

Architecture Comparison

DEMO (this page):
  Customer Browser → Gemini API → Browser renders reply

PRODUCTION:
  Customer WhatsApp → WhatsApp Business API → Backend Server → LLM API → Backend → WhatsApp API → Customer WhatsApp
  + SQLite/Firestore for conversation persistence
  + Session timeout logic (24hr follow-up, then close)
  + Per-phone-number conversation threads
            

Development Setup & Installation Guide

Prerequisites

Google Gemini API Key from aistudio.google.com (free tier available)
Any modern browser (Chrome, Firefox, Edge)

Quick Start

# Clone the repository
git clone https://github.com/lyven81/ai-project.git
cd ai-project/projects/plumber-whatsapp-agent

# Open the demo directly in a browser
# Windows:
start demo.html
# Mac:
open demo.html

# Or regenerate the booking seed data:
python generate_seed.py
            

Project Files

projects/plumber-whatsapp-agent/
  demo.html              # Main app — WhatsApp-style chat UI with embedded schedule
  generate_seed.py       # Python script to generate booking seed data
  plumber_bookings.json  # Generated 7-day schedule (23 bookings, 49% occupancy)
  system-prompt.txt      # Jamal's system prompt (bahasa santai, 5-step flow)
  project-outline.md     # Full project design document
  problem-statement.md   # Problem statement and market fit analysis
  user-guide.md          # Plain-language usage guide
            

Key Metrics

~1,000

Tokens Per Turn

5

Guided Conversation Steps

10

Plumbing Service Types

49%

Schedule Pre-Booked

Business Value

Zero Missed Leads: Every inquiry gets an instant reply, converting idle WhatsApp messages into confirmed bookings
4-5x Cost Efficiency: Lean LLM architecture uses ~1,000 tokens/turn vs ~5,000 for framework-based agents — near-zero operating cost with BYO API key
Zero Behavior Change: Both the plumber and the customer keep using WhatsApp exactly as they already do — no new app to learn
Localized & Natural: Bahasa santai output makes the agent indistinguishable from a real Malaysian plumber texting
Production-Ready Path: Clear upgrade from demo (GitHub Pages) to production (WhatsApp Business API + Cloud Run) with documented architecture