========================================================
  SYANKO <3U — WhatsApp Ordering + Loyalty Integration
  HotelFinder Project Notes
========================================================

WHAT THIS DOES
--------------
Customers can message the restaurant's WhatsApp number to:
  • Browse the full menu by category
  • Add items to a cart
  • Check their loyalty coin balance
  • Use coins as discount at checkout (Iron Law: max 50% of bill)
  • Pay using Cash / UPI / Khata (Pay Later lifeline)
  • Check subscription (Liquid Gold Pass) status
  • See their Summit VIP progress after every order
  • Earn coins automatically on every order placed

All loyalty benefits are live inside the WhatsApp conversation —
no app needed for repeat customers once registered.


FILES CREATED / MODIFIED
-------------------------
backend/hotelfinder/restaurant/whatsapp_session.py  (NEW)
  - Redis-backed session per phone number (30-min TTL)

backend/hotelfinder/restaurant/whatsapp_webhook.py  (NEW)
  - Full conversation state machine:
    IDLE → AWAITING_RESTAURANT → MAIN_MENU
    → MENU_CATEGORIES → MENU_ITEMS → CART
    → CHECKOUT_COINS → CHECKOUT_PAYMENT → (order placed)
  - WhatsAppWebhookView: POST (inbound), GET (verification)

backend/hotelfinder/restaurant/whatsapp_service.py  (MODIFIED)
  - Added send_reply(phone, message) for freeform session replies

backend/hotelfinder/restaurant/urls.py  (MODIFIED)
  - Added: POST /api/restaurants/whatsapp/webhook/


WATI SETUP (3 steps)
---------------------
1. Create WATI account at wati.io
   - Connect your WhatsApp Business number
   - Under Settings → API → copy your API Endpoint and API Token

2. Set environment variables in .env:
   WHATSAPP_API_URL=https://live-server-XXXXX.wati.io
   WHATSAPP_API_KEY=eyJ0eXAiOiJKV1Q...  (your token)
   WHATSAPP_FROM_NUMBER=919876543210    (your WA business number)

3. Configure WATI Webhook:
   - WATI Dashboard → Settings → Webhook
   - Webhook URL: https://yourdomain.com/api/restaurants/whatsapp/webhook/
   - Events: message received
   - Save & Test

   For local dev use ngrok:
     ngrok http 8000
     → Paste the https URL into WATI webhook settings


INTERAKT SETUP (recommended)
----------------------------
1. Set these environment variables in backend/hotelfinder/.env:
   WHATSAPP_PROVIDER=interakt
   INTERAKT_SECRET_KEY=<Interakt Developer Settings Secret Key>
   INTERAKT_WEBHOOK_SECRET=<Interakt webhook secret>

   Optional, only if your Interakt Track API key differs from the WhatsApp API key:
   INTERAKT_TRACK_KEY=<base64-decoded Interakt Track key without trailing colon>

2. Configure Interakt inbound webhook:
   Webhook URL: https://yourdomain.com/api/restaurants/whatsapp/webhook/
   Event: message received / inbound WhatsApp message
   Secret: same value as INTERAKT_WEBHOOK_SECRET

3. Make sure each live restaurant has menu items and, if orders must reach Aahar POS,
   an active Aahar link in Admin → Aahar Integration.


CONVERSATION FLOW (example)
----------------------------
Customer:  "Hi"
Bot:       "Welcome back, Rahul! Which restaurant are you ordering from?"

Customer:  "Syanko Kitchen"   (or just the ID: "5")
Bot:       "Syanko Kitchen
            💰 Coins: 450
            1. View Menu
            2. My Wallet
            3. Subscription
            4. Pay Later (Khata)
            9. Change Restaurant"

Customer:  "1"
Bot:       "Menu — Syanko Kitchen
            1. Starters
            2. Main Course
            3. Biryani
            4. Beverages"

Customer:  "3"
Bot:       "Biryani
            1. 🔴 Chicken Biryani — ₹220
            2. 🟢 Veg Biryani — ₹160
            Format: number + qty (e.g. 2 1)"

Customer:  "1 2"
Bot:       "✅ Added 2× Chicken Biryani (+₹440)
            Cart total: ₹440
            Add more or type done to checkout."

Customer:  "done"
Bot:       "Cart:
            • 2× Chicken Biryani — ₹440
            Subtotal: ₹440
            💰 450 coins → use up to 220 coins = ₹22 off
            1. Checkout  2. Add More  3. Clear"

Customer:  "1"
Bot:       "💰 Use Loyalty Coins?
            YES — use all 220 coins
            NO  — skip"

Customer:  "YES"
Bot:       "Payment
            Order total:    ₹440
            💰 Coins:       -₹22
            You pay:        ₹418
            1. Cash/Card
            3. Pay Later — Khata (3 lifelines left)"

Customer:  "1"
Bot:       "✅ Order #1042 Confirmed!
            Syanko Kitchen
            💵 You pay: ₹418
            💰 Coins balance: 174
            🏔️ Summit: ██████░░░░ 62% (₹4340/₹7000)
            ⏱️ Your order is being prepared."


LOYALTY BENEFITS IN WHATSAPP — SUMMARY
---------------------------------------
✅ Coin balance shown on main menu and cart screen
✅ Coin redemption at checkout (50% cap auto-enforced)
✅ Khata lifeline offered as payment option if available
✅ Subscription status viewable + reminder to use free drink today
✅ Coins earned automatically after order (RulesEngine fires)
✅ Summit VIP progress shown on every order confirmation
✅ Dead-Hour Drops delivered as WhatsApp push (already built)
✅ Coin expiry warnings delivered as WhatsApp push (already built)
✅ Welcome coins on first order (signal fires on wallet creation)


PRE-REQUISITES
--------------
• Redis must be running (already needed for Celery)
• Django CACHES must point to Redis:
    CACHES = {
        "default": {
            "BACKEND": "django_redis.cache.RedisCache",
            "LOCATION": "redis://127.0.0.1:6379/1",
        }
    }
  Install: pip install django-redis
• Customer's phone_number in User model must match their WhatsApp number
  (without country code prefix is fine — both formats are tried)


KNOWN LIMITATIONS
-----------------
• First-time users (no HotelFinder account) can browse menu but cannot
  place an order — they get a prompt to download the app.
• Images are not sent (text-only for now). WhatsApp media messages
  require approved templates or interactive message types.
• Table reservations (Dine-In) are not yet supported via WhatsApp —
  only TAKEAWAY orders are created.
• Payment gateway integration (Razorpay / UPI deep link) is not wired —
  "Cash/Card" just marks payment_status=PAID on faith; real payment
  confirmation needs a Razorpay webhook or QR flow.

========================================================