Executive Overview

Traditional WhatsApp businesses rely heavily on manual responses, delayed quotations, manual payment confirmation and human product recommendation. This project replaces that workflow with an AI-powered assistant capable of understanding customer intent, recommending products, retrieving catalogue information, sending product images, creating orders, logging conversations and transferring customers to human staff whenever necessary.

Business Problem

• Slow response time
• Manual product recommendation
• No conversation history
• Difficulty managing hundreds of enquiries
• Delayed payment confirmation
• No automated order workflow

System Architecture

Customer
    │
WhatsApp
    │
Meta Cloud API
    │
Webhook
    │
Flask Backend
 ├── AI Agent
 ├── Product Search
 ├── Image Service
 ├── Order Engine
 ├── Payment Verification
 └── SQLite Database

Frontend

• Responsive Admin Dashboard
• Product Management
• Conversation Monitor
• Chat Simulator
• Story Manager
• Order Dashboard
• Image Upload Preview

Backend Engineering

The backend was implemented in Flask and exposes REST endpoints for products, orders, stories, uploads, conversations, webhook verification, payment verification and AI interactions.

• RESTful API
• SQLite persistence
• Webhook processing
• Static image serving
• Conversation logging
• Human handoff support

Meta WhatsApp Cloud API Integration

A Meta Developer application was configured together with a Business Portfolio, WhatsApp Business Account, permanent access token, phone number ID, application secrets and webhook subscriptions.

1. Create Meta App
2. Add WhatsApp Product
3. Generate Access Token
4. Configure Phone Number
5. Register Callback URL
6. Verify Webhook Token
7. Subscribe to Messages

Webhook Configuration

Incoming customer messages arrive through the webhook endpoint where payloads are validated, parsed and dispatched to the AI engine. Image requests trigger catalogue search and image delivery before conversational responses are generated.

Database Design

• Products
• Customers
• Orders
• Story Items
• Conversation Logs

Admin Console

• Create Products
• Edit Products
• Delete Products
• Upload Product Images
• Manage Stories
• Monitor Orders
• Pause AI
• Resume AI
• Manual Customer Replies

AI Conversation Engine

The conversational engine performs intent detection, semantic catalogue search, conversation memory retrieval, recommendation generation and structured sales responses. Image requests are identified separately and resolved through the upload service before text generation.

Payment Verification Workflow

Customers submit payment evidence through WhatsApp. The backend validates transaction metadata, records payment status, updates the order lifecycle and notifies administrators for fulfilment. This architecture supports future integration with payment gateways such as Paystack or Flutterwave.

Product Image Pipeline

• Local image upload
• UUID file naming
• Persistent upload directory
• Static Flask routing
• Automatic public URL generation
• WhatsApp media delivery

Deployment

The application was deployed on Render with environment variables for Meta credentials, webhook verification, API keys and public base URL. Special attention was given to persistent storage limitations, SQLite handling, static uploads and webhook accessibility.

Engineering Challenges

• Recovering lost Git commits using reflog and VS Code local history.
• Render ephemeral storage affecting uploaded images.
• Webhook debugging.
• Serving uploaded media publicly.
• Synchronising AI responses with image delivery.
• Conversation persistence.
• SQLite deployment considerations.

Technology Stack

• Python
• Flask
• SQLite
• HTML5
• CSS3
• JavaScript
• Meta WhatsApp Cloud API
• OpenAI LLM Integration
• Render
• Git & GitHub

Future Roadmap

• PostgreSQL migration
• Vector search
• Recommendation models
• Voice notes
• Inventory forecasting
• Sales analytics dashboard
• Customer segmentation
• Multi-store support