# CustomerFlow — Comprehensive Platform & Technical Reference (llms-full.txt)

> Complete architectural, functional, integration, and operational manual of CustomerFlow for AI agents, LLMs, search engines, and technical developers.

## 1. Platform Summary

CustomerFlow (formerly ShopDost) is an enterprise-grade, multi-tenant AI automation platform engineered specifically for e-commerce and retail merchants operating on WhatsApp. It replaces manual chat-handling with a synchronized system of:
1. Meta WhatsApp Cloud API v19.0 webhooks.
2. Context-aware conversational AI models (OpenAI GPT-4o-mini & Google Gemini 2.5 Flash).
3. Real-time product catalogue and variant inventory database.
4. Intelligent order structuring and automated UPI bill receipt generator.
5. Multi-staff inbox routing with 1-click human takeover and zero-interruption handoff guarantees.
6. Visual drag-and-drop Kanban fulfillment pipeline.

---

## 2. Supported Retail Verticals & Use Cases

- **Dry Fruits, Spices & Gourmet Foods**: High inquiry volumes around quality, grade (W240, W320 cashews), origins, and dynamic weight pack pricing (250g, 500g, 1kg).
- **Fashion, Apparel & Ethnic Wear**: Size selection (S, M, L, XL, XXL), color variations, fabric care instructions, and photo requests.
- **Organic Grocery & Daily Staples**: Weekly recurring grocery lists, delivery slot preferences, address verification, and cash-free UPI payments.
- **Electronics & Mobile Accessories**: Model compatibility checks, warranty queries, and fast dispatch coordination.
- **Beauty, Cosmetics & Wellness**: Product application advice, ingredient inquiries, and bundle discounts.
- **Bakery, Cakes & Sweets**: Custom message-on-cake capture, weight sizing, store pickup vs doorstep delivery scheduling.

---

## 3. Conversational AI Workflow & Rules Engine

### 3.1 Catalogue Grounding & Anti-Hallucination
The AI engine dynamically constructs its system prompt on every inbound message using live store data:
- **Active Products**: Filtered by tenant shop ID, incorporating variant names, unit prices, SKU, and live stock quantities.
- **Store Locations**: Multi-branch physical addresses, opening/closing hours, and validated Google Maps URLs.
- **Payment & Delivery Policies**: Free delivery thresholds, standard shipping rates, and UPI payment IDs.
- **Language Detection & Matching**: Fluidly communicates in English, Hindi, and Hinglish (e.g. *"Bhaiya 1kg Almonds pack kardo"*).

### 3.2 Automated Order Extraction & Bill Receipt Emission
When a customer indicates an intent to buy and provides their address:
1. **Entity Extraction**: Item names, quantities, variant weights, customer name, phone number, and complete delivery address are extracted.
2. **Bill Calculation**: Subtotal, applicable shipping, and total order value are computed accurately.
3. **Database Insertion**: An `Order` record is generated in MySQL with status `order_received` and payment status `pending` (UPI mode).
4. **Inventory Update**: Stock levels are automatically decremented to prevent overselling.
5. **Formatted Receipt Emission**: A clean, structured WhatsApp bill receipt is sent back to the customer with UPI transfer instructions.

---

## 4. Human-in-the-Loop & Staff Collaboration

### 4.1 1-Click Mode Handoff
- **AI Mode**: The conversational engine automatically replies to incoming messages within a 3-second debounce window.
- **Human Mode**: When a staff member is assigned or manually claims a conversation, `handling_mode` transitions to `human`. The AI auto-reply queue is strictly bypassed, ensuring no accidental bot messages interfere with human negotiation.
- **Let AI Handle Button**: A single click resumes AI autonomy, catching up on recent customer messages.

### 4.2 Multi-Staff Routing & Inactivity Alarms
- Store owners can create multiple staff seats (`shop_owner`, `staff`, `admin`).
- Unanswered human chats are tracked with `last_customer_message_at` and `last_staff_message_at`.
- Visual badges alert the team when a customer has been waiting for staff attention (`Waiting 2h+`).

---

## 5. Orders Kanban Fulfillment Board

The platform provides a 4-column reactive Kanban board:
1. **Order Received (`order_received`)**: Newly created automated or manual orders awaiting preparation.
2. **Ready to Dispatch (`ready_to_dispatch`)**: Packaged orders ready for courier pickup.
3. **Out for Delivery (`out_for_delivery`)**: In-transit orders with courier tracking.
4. **Delivered (`delivered`)**: Successfully completed transactions.

### Features:
- Natural drag-and-drop with responsive position insertion.
- Direct internal chat linking: Clicking customer phone numbers opens `/chat#conv-{id}` instantly.
- Manual order creator with auto-complete customer lookup and live variant selection.

---

## 6. Technical Stack & Security

- **Framework**: Laravel 12 (PHP 8.2+)
- **Database**: MySQL with relational foreign keys and indexes.
- **Real-Time Layer**: Laravel Reverb self-hosted WebSockets.
- **Webhook Security**: Meta HMAC-SHA256 signature verification via `X-Hub-Signature-256`.
- **SSRF Protection**: Private/internal IP range blocking for external scraper and webhook utilities.
- **Rate Limiting**: Custom token bucket throttles on webhooks and authentication endpoints.

---

## 7. Pricing & Subscription Tiers

- **Starter Plan**: ₹1,499/month — 1 WhatsApp number, 500 customers, 24/7 AI catalogue replies, orders board.
- **Growth Plan**: ₹2,999/month — Unlimited customers, 3 staff seats, automated UPI receipts, WooCommerce 2-way sync, product photo sender.
- **Enterprise / Scale Plan**: ₹5,999/month — Unlimited staff seats, multi-store Google Maps sync, dedicated server, custom AI fine-tuning.

---

## 8. Web URLs & Endpoints

- **Homepage**: https://customerflow.net/
- **Sign In**: https://customerflow.net/login
- **Free Trial Registration**: https://customerflow.net/register
- **Sitemap**: https://customerflow.net/sitemap.xml
- **Robots.txt**: https://customerflow.net/robots.txt
- **LLMs Summary**: https://customerflow.net/llms.txt
- **LLMs Full Manual**: https://customerflow.net/llms-full.txt
- **Privacy Policy**: https://customerflow.net/privacy-policy
- **Terms of Service**: https://customerflow.net/terms