WhatsApp Bot - Complete Logic Flow Guide (Non-Technical)

🎯 Overview

This document explains WHAT happens at each step of the WhatsApp bot, without code. Perfect for understanding the user experience and bot behavior.

📱 Entry Points - How Users Start

Entry Point 1: Direct WhatsApp Message

User opens WhatsApp → Sends "Hi" to Yugam number → Bot responds with welcome

Entry Point 2: Website Login Page

User on website → Clicks "Continue with WhatsApp" → Enters phone → 
WhatsApp opens → Sends message → Bot sends login link → Click link → Logged in

🎬 FIRST INTERACTION - Registration Check

When user sends “Hi”, “Hello”, “Start”, or any first message:

Step 1: Bot Checks User in Database

What bot does:

1. Receives message from phone number (e.g., +919876543210)
2. Searches database: SELECT * FROM tbl_users WHERE phone = '+919876543210'
3. Checks if user exists

Step 2A: User EXISTS (Already Registered)

Bot sends:

┌────────────────────────────────────────┐
│  👋 Hi Rajesh Kumar!                   │
│                                        │
│  Welcome back to Yugam 2026! 🎉       │
│                                        │
│  Your Yugam ID: YUG2600001              │
│                                        │
│  What would you like to do today?     │
└────────────────────────────────────────┘

Then immediately shows Main Menu (see below)

What happens internally:

• User found in database
• Fetches name and Yugam ID from database
• Shows personalized welcome
• State changes to idle
• Proceeds to main menu

Step 2B: User DOES NOT EXIST (New User)

Bot sends:

┌────────────────────────────────────────┐
│  👋 Welcome to Yugam 2026!             │
│                                        │
│  You haven't registered yet.          │
│                                        │
│  Let's create your account! 🚀        │
│                                        │
│  Please answer the following          │
│  questions to get started.            │
└────────────────────────────────────────┘

Then immediately starts Registration Flow (see below)

What happens internally:

• User not found in database
• State changes to registration_start
• Bot initiates one-by-one question flow

📝 REGISTRATION FLOW (For New Users)

Step 1: Collect Name

Bot sends:

┌────────────────────────────────────────┐
│  📝 Registration - Step 1/5            │
│                                        │
│  What is your full name?              │
│                                        │
│  Example: Rajesh Kumar                │
└────────────────────────────────────────┘

User replies: Rajesh Kumar

What happens internally:

• Bot saves: name = "Rajesh Kumar" (temporary storage)
• State changes to collecting_email

Step 2: Collect Email (Gmail ID Only)

Bot sends:

┌────────────────────────────────────────┐
│  📝 Registration - Step 2/5            │
│                                        │
│  What is your Gmail ID?               │
│                                        │
│  ⚠️ Please enter a valid Gmail        │
│  address ending with @gmail.com       │
│                                        │
│  Example: rajesh.kumar@gmail.com      │
└────────────────────────────────────────┘

User replies: rajesh@gmail.com

What bot does:

1. Validates format (must contain @gmail.com)
2. Checks if email already exists in database
3. If valid and unique → Proceeds
4. If invalid → Asks again
5. If already exists → Shows error

If email format is invalid:

┌────────────────────────────────────────┐
│  ❌ Invalid email format               │
│                                        │
│  Please enter a valid Gmail address   │
│  ending with @gmail.com               │
│                                        │
│  Example: yourname@gmail.com          │
└────────────────────────────────────────┘

If email already registered:

┌────────────────────────────────────────┐
│  ⚠️ Email Already Registered           │
│                                        │
│  This Gmail ID is already linked     │
│  to Yugam ID: YUG26XXXXX             │
│                                        │
│  Please enter a different email or    │
│  contact support if this is your      │
│  account.                             │
└────────────────────────────────────────┘

If email is valid:

Bot saves: email = "rajesh@gmail.com"
State changes to collecting_college

Step 3: Select College/School (From Database)

Bot sends:

┌────────────────────────────────────────┐
│  📝 Registration - Step 3/5            │
│                                        │
│  Select your College/School:          │
│  [Search Colleges ▼]                  │
│                                        │
│  When clicked, shows:                 │
│  🔍 Search box                        │
│                                        │
│  Complete list from database:         │
│  • PSG College of Technology          │
│  • Anna University                    │
│  • VIT Vellore                        │
│  • Coimbatore Institute of Tech       │
│  • Amrita University                  │
│  • St. Joseph's College               │
│  • Kumaraguru College of Tech         │
│  ... (ALL colleges from DB)           │
│                                        │
│  • Other (Type manually)              │
└────────────────────────────────────────┘

What bot does:

1. Queries database: SELECT id, name FROM tbl_colleges ORDER BY name ASC
2. Shows as interactive list with search
3. ALL colleges shown, not limited to 10-20
4. User can search to filter
5. Last option: “Other (Type manually)”

Interactive List Features:

• 🔍 Search box at top
• User types to filter results
• Shows all matching colleges dynamically
• Scrollable list

User selects: “PSG College of Technology”

What happens internally:

• Bot saves: college_id = 5 and college_name = "PSG College of Technology"
• State changes to collecting_department

If user selects “Other”:

Bot sends:

┌────────────────────────────────────────┐
│  Please type your college/school name:│
└────────────────────────────────────────┘

User types: St. Xavier's College

What happens internally:

• Bot saves: college_id = NULL and college_name = "St. Xavier's College"
• Custom college stored as text
• State changes to collecting_department

Step 4: Select Department (From Database)

Bot sends:

┌────────────────────────────────────────┐
│  📝 Registration - Step 4/5            │
│                                        │
│  Select your Department:              │
│  [Search Departments ▼]               │
│                                        │
│  When clicked, shows:                 │
│  🔍 Search box                        │
│                                        │
│  Complete list from database:         │
│  • Computer Science Engineering       │
│  • Electronics & Communication        │
│  • Mechanical Engineering             │
│  • Civil Engineering                  │
│  • Information Technology             │
│  • Electrical Engineering             │
│  • Business Administration            │
│  • Artificial Intelligence            │
│  • Data Science                       │
│  • Biotechnology                      │
│  ... (ALL departments from DB)        │
│                                        │
│  • Other (Type manually)              │
└────────────────────────────────────────┘

What bot does:

1. Queries database: SELECT id, name FROM tbl_departments ORDER BY name ASC
2. Shows as interactive list with search
3. ALL departments shown, not limited to 10-20
4. User can search to filter (e.g., type “Computer” shows CS-related)
5. Last option: “Other (Type manually)”

Interactive List Features:

• 🔍 Search box at top
• User types “mech” → filters to Mechanical, Mechatronics, etc.
• Shows all matching departments dynamically
• Scrollable list

User selects: “Computer Science Engineering”

What happens internally:

• Bot saves: department_id = 1 and department_name = "Computer Science Engineering"
• State changes to collecting_year

If user selects “Other”:

Bot sends:

┌────────────────────────────────────────┐
│  Please type your department name:    │
└────────────────────────────────────────┘

User types: Marine Engineering

What happens internally:

• Bot saves: department_id = NULL and department_name = "Marine Engineering"
• Custom department stored as text
• State changes to collecting_year

Step 5: Collect Year of Study

Bot sends:

┌────────────────────────────────────────┐
│  📝 Registration - Step 5/5            │
│                                        │
│  What year are you in?                │
│  [Select Year ▼]                      │
│                                        │
│  When clicked, shows:                 │
│  • 1st Year                           │
│  • 2nd Year                           │
│  • 3rd Year                           │
│  • 4th Year                           │
│  • Postgraduate                       │
│  • Alumni                             │
│  • Faculty                            │
│  • Other                              │
└────────────────────────────────────────┘

User selects: “2nd Year”

What happens internally:

• Bot saves: year = "2nd Year"
• State changes to registration_summary

Step 6: Summary & Account Creation

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Registration Summary               │
│                                        │
│  Please confirm your details:         │
│                                        │
│  Name: Rajesh Kumar                   │
│  Email: rajesh@gmail.com              │
│  College: PSG College of Technology   │
│  Department: Computer Science Engg    │
│  Year: 2nd Year                       │
│  Phone: +919876543210                 │
│                                        │
│  Is this correct?                     │
│                                        │
│  [✅ Confirm]  [❌ Edit]              │
└────────────────────────────────────────┘

What happens internally:

• Bot shows all collected data
• Waits for confirmation
• State: registration_summary

If user clicks “Edit”:

Bot sends:

┌────────────────────────────────────────┐
│  Which field do you want to edit?     │
│  [View Fields ▼]                      │
│                                        │
│  • Name                               │
│  • Email                              │
│  • College                            │
│  • Department                         │
│  • Year                               │
│  • Cancel (Keep all)                  │
└────────────────────────────────────────┘

User selects: “Email”

What happens:

• Bot goes back to Step 2 (email collection)
• User enters new email
• Bot validates and updates
• Returns to summary screen

If user clicks “Confirm”:

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Creating Your Account...           │
└────────────────────────────────────────┘

What happens internally:

1. Creates user record in database:

   INSERT INTO tbl_users (
     name, email, phone, college_id, 
     department_id, year, 
     created_at
   ) VALUES (
     'Rajesh Kumar',
     'rajesh@gmail.com',
     '+919876543210',
     5,
     1,
     '2nd Year',
     NOW()
   )
   

2. Generates Yugam ID: YUG2600001 (format: YUG + year + 5-digit number)
3. Updates user record with Yugam ID
4. State changes to registration_complete

Then bot sends:

┌────────────────────────────────────────┐
│  🎉 Registration Successful!           │
│                                        │
│  Welcome to Yugam 2026, Rajesh! 🚀    │
│                                        │
│  Your Yugam ID: YUG2600001              │
│                                        │
│  Save this ID - you'll need it for    │
│  team registrations!                  │
│                                        │
│  Confirmation sent to your email.     │
└────────────────────────────────────────┘

Then immediately shows Main Menu (see below)

🏠 MAIN MENU - After Registration/Login

After successful registration OR when existing user says “Hi”:

Bot sends:

┌────────────────────────────────────────┐
│  👋 Welcome to Yugam 2026!            │
│                                        │
│  What would you like to do?           │
│                                        │
│  [📅 Browse Events]                   │
│  [🎓 Browse Workshops]                │
│  [🎟️ Buy General Pass]                │
└────────────────────────────────────────┘

Then immediately sends:
┌────────────────────────────────────────┐
│  Or manage your account:              │
│                                        │
│  [📝 My Registrations]                │
│  [👥 My Teams]                        │
│  [👤 My Profile]                      │
└────────────────────────────────────────┘

User’s phone state changes to: idle

📅 OPTION 1: BROWSE EVENTS

Step 1: User Clicks “Browse Events”

Bot sends:

┌────────────────────────────────────────┐
│  📅 Browse Events                      │
│                                        │
│  Select a category:                   │
│  [View Events ▼]                      │
│                                        │
│  When clicked, shows list:            │
│  • 🎟️ General Events                  │
│  • 🎯 Specific Events                 │
│  • 🌟 All Events                      │
└────────────────────────────────────────┘

What happens internally:

• Bot saves user’s state as browsing_events
• Bot waits for category selection

Note on Event Types:

• General Events: Events that can be attended with a General Event Pass
• Specific Events: Specialized events requiring individual registration and payment

Step 2: User Selects “Specific Events”

What bot does:

1. Searches database for all Specific events that are:
   • Currently active
   • Registration is open (dates valid)
   • event_type = ‘specific’
2. Finds, for example: 5 specific events
3. Formats them into a list

Bot sends:

┌────────────────────────────────────────┐
│  🎯 Specific Events                    │
│                                        │
│  Select an event:                     │
│  [View Event ▼]                       │
│                                        │
│  When clicked, shows:                 │
│  1. Code Marathon                     │
│     ₹200 • Feb 15, 2026              │
│                                        │
│  2. Hackathon 24hrs                   │
│     ₹500 • Feb 16, 2026              │
│                                        │
│  3. AI/ML Workshop                    │
│     ₹300 • Feb 17, 2026              │
│                                        │
│  ... (up to 10 events)                │
└────────────────────────────────────────┘

What happens internally:

• State remains browsing_events
• Bot waits for event selection

Step 3A: User Selects a SPECIFIC Event (e.g., “Code Marathon”)

What bot does:

1. Gets complete event details from database
2. Checks event_type = ‘specific’
3. Formats all event information

Bot sends:

┌────────────────────────────────────────┐
│  📅 Code Marathon (Specific)           │
│                                        │
│  48-hour coding challenge where       │
│  teams build innovative solutions...  │
│                                        │
│  📍 Venue: CSE Lab                    │
│  📅 Date: Feb 15, 2026                │
│  ⏰ Time: 9:00 AM                     │
│  💰 Fee: ₹200                         │
│  👥 Team Size: 2-4 members            │
│  🎯 Type: Specific Event              │
│                                        │
│  📄 Rules: [link]                     │
│                                        │
│  Ready to register?                   │
│                                        │
│  [✅ Register Now]                    │
│  [◀️ Back to Events]                  │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

What happens internally:

• State changes to specific_event_details
• Bot saves event ID (e.g., “code_marathon_2026”)
• Bot waits for user action

Step 3B: User Selects a GENERAL Event (e.g., “College Fest Day”)

What bot does:

1. Gets complete event details from database
2. Checks event_type = ‘general’
3. Checks if user has General Event Pass for this date
4. Formats all event information

If user HAS General Event Pass:

Bot sends:

┌────────────────────────────────────────┐
│  📅 College Fest Day (General)         │
│                                        │
│  Join the opening ceremony and        │
│  various cultural activities...       │
│                                        │
│  📍 Venue: Main Auditorium            │
│  📅 Date: Feb 15, 2026                │
│  ⏰ Time: 10:00 AM                    │
│  💰 Fee: ✅ Already Purchased         │
│     (General Event Pass)              │
│  👥 Entry: Individual                 │
│  🎯 Type: General Event               │
│                                        │
│  You have a valid General Event Pass! │
│                                        │
│  [✅ Register Now]                    │
│  [◀️ Back to Events]                  │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

If user DOES NOT have General Event Pass:

Bot sends:

┌────────────────────────────────────────┐
│  📅 College Fest Day (General)         │
│                                        │
│  Join the opening ceremony and        │
│  various cultural activities...       │
│                                        │
│  📍 Venue: Main Auditorium            │
│  📅 Date: Feb 15, 2026                │
│  ⏰ Time: 10:00 AM                    │
│  💰 Fee: Requires General Pass        │
│     (₹2999 for all general events)   │
│  👥 Entry: Individual                 │
│  🎯 Type: General Event               │
│                                        │
│  Purchase General Event Pass to       │
│  attend this and all general events!  │
│                                        │
│  [🎟️ Buy General Pass]               │
│  [◀️ Back to Events]                  │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

What happens internally:

• State changes to general_event_details
• Bot saves event ID
• Bot checks tbl_registrations for general_pass registration with valid dates
• Bot waits for user action

Step 4: User Clicks “Register Now” (SPECIFIC or GENERAL Event)

Note: No login check needed - user is already on WhatsApp bot!

What bot does:

1. Checks if event has “before_payment_form”
2. If YES → Proceeds to form collection (Step 5)
3. If NO → Proceeds directly to registration confirmation (Step 6)

Step 5: Before Payment Form Collection (If Required)

If event has before_payment_form = true:

Bot sends:

┌────────────────────────────────────────┐
│  📝 Registration Form                  │
│                                        │
│  Please answer a few questions        │
│  before we proceed:                   │
│                                        │
│  Question 1: What is your t-shirt     │
│  size? (S/M/L/XL/XXL)                 │
└────────────────────────────────────────┘

User replies: L

Bot sends:

┌────────────────────────────────────────┐
│  Question 2: Any dietary              │
│  restrictions? (Yes/No)               │
└────────────────────────────────────────┘

User replies: No

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Form Completed!                    │
│                                        │
│  Your answers:                        │
│  • T-shirt size: L                    │
│  • Dietary restrictions: No           │
│                                        │
│  Proceeding to registration...        │
└────────────────────────────────────────┘

What happens internally:

• State changes to collecting_form_data
• Bot stores form responses in session
• After all questions answered → Creates registration record
• If General Event + Pass Purchased: Mark registration as paid
• Proceeds to confirmation

Step 6A: Registration Confirmation (SPECIFIC Event, Individual)

After form completion (or if no form), bot creates registration record

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Registration Created!              │
│                                        │
│  Event: Code Marathon                 │
│  Registration ID: REG123456           │
│  Fee: ₹200                            │
│                                        │
│  Would you like to proceed to         │
│  payment?                             │
│                                        │
│  [💳 Proceed to Payment]              │
│  [❌ Cancel]                          │
└────────────────────────────────────────┘

What happens internally:

1. Bot creates registration in database:
   • User ID: YUG2600001
   • Event ID: code_marathon_2026
   • Type: Individual
   • Status: Pending payment
   • Form data: Saved (if collected)
2. Bot waits for payment confirmation

If user clicks “Proceed to Payment”:

• Goes to Payment Flow (Step 7)

Step 6B: Registration Confirmation (GENERAL Event with Pass)

If user has General Event Pass:

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Registration Confirmed!            │
│                                        │
│  Event: College Fest Day              │
│  Registration ID: REG123456           │
│  Fee: ✅ Covered by General Pass      │
│                                        │
│  You're all set! No payment needed.   │
│                                        │
│  Event Details:                       │
│  📅 Feb 15, 2026                      │
│  ⏰ 10:00 AM                          │
│  📍 Main Auditorium                   │
│                                        │
│  Show your General Pass QR at entry.  │
│                                        │
│  [🏠 Main Menu]                       │
│  [📅 Browse More Events]              │
└────────────────────────────────────────┘

What happens internally:

1. Bot creates registration in database:
   • User ID: YUG2600001
   • Event ID: college_fest_day_2026
   • Type: Individual
   • Status: Confirmed
   • Payment Status: Paid (covered by general pass)
   • Linked to general pass registration
2. Registration is complete - no payment needed!
3. State returns to idle

Step 6C: Registration Confirmation (GENERAL Event without Pass)

If user does NOT have General Event Pass:

Bot sends:

┌────────────────────────────────────────┐
│  🎟️ General Event Pass Required       │
│                                        │
│  To attend "College Fest Day" and     │
│  ALL other general events, purchase   │
│  the General Event Pass!              │
│                                        │
│  Price: ₹2999                         │
│  Valid: Feb 15-18, 2026               │
│                                        │
│  Includes access to:                  │
│  ✓ All General Events                 │
│  ✓ Opening & Closing Ceremonies       │
│  ✓ Cultural Activities                │
│                                        │
│  Would you like to purchase?          │
│                                        │
│  [🛒 Buy General Pass]                │
│  [❌ Cancel]                          │
└────────────────────────────────────────┘

What happens internally:

• State changes to buying_general_pass
• Bot waits for purchase confirmation

If user clicks “Buy General Pass”:

• Goes to General Pass Purchase Flow (see Option 4)

Step 6D: User Clicks “Register Now” (TEAM EVENT)

Team Event = Requires 2+ members

Bot sends:

┌────────────────────────────────────────┐
│  👥 Team Formation                     │
│                                        │
│  Event: Code Marathon                 │
│  Team Size: 2-4 members               │
│                                        │
│  You are the team leader.             │
│                                        │
│  How to add members:                  │
│  Send Yugam IDs of your team members │
│  separated by commas.                 │
│                                        │
│  Example: YUG2600002, YUG2600003          │
│                                        │
│  Or type "skip" to register alone     │
│  (if minimum is 1).                   │
└────────────────────────────────────────┘

What happens internally:

• State changes to team_formation
• Bot creates empty team list
• Bot waits for user input

Step 7: Team Formation Flow (AFTER Payment Success)

After payment success message is sent, bot checks event details:

What bot checks internally:

1. Gets event from database
2. Checks if team_size > 1 (indicates team event)
3. If yes → Proceeds to team formation prompt
4. If no → Registration complete, no team needed

If team_size > 1 (Team Event):

Bot sends:

┌────────────────────────────────────────┐
│  👥 Team Event Detected                │
│                                        │
│  "Code Marathon" is a team event!     │
│  Team Size: 4 members                 │
│                                        │
│  You have already paid and registered.│
│                                        │
│  Would you like to create a team?     │
│                                        │
│  [✅ Yes, Create Team]                │
│  [❌ No, Skip]                        │
└────────────────────────────────────────┘

What happens internally:

• State changes to team_creation_prompt
• Bot waits for user response

If user clicks “No, Skip”:

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Registration Complete              │
│                                        │
│  You can create a team later via      │
│  "My Teams" option in the main menu.  │
│                                        │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

What happens internally:

• Registration remains as individual
• User can create team later via My Teams
• State returns to idle

If user clicks “Yes, Create Team”:

Bot sends:

┌────────────────────────────────────────┐
│  👥 Create Your Team                   │
│                                        │
│  Event: Code Marathon                 │
│  Team Size: 4 members (including you) │
│                                        │
│  You are the team leader.             │
│                                        │
│  Please send Yugam IDs of your        │
│  3 team members separated by commas.  │
│                                        │
│  Example: YUG2600002, YUG2600003, YUG2600004│
│                                        │
│  ⚠️ Important: All members must have  │
│  registered and paid for this event.  │
└────────────────────────────────────────┘

What happens internally:

• State changes to collecting_team_members
• Bot waits for Yugam IDs

User sends: YUG2600002, YUG2600003, YUG2600004, YUG2600005, YUG2600006

What bot does:

1. Splits the message by commas
2. Takes only first 3 IDs (team_size - 1 = 4 - 1 = 3)
3. Ignores excess IDs (YUG2600005, YUG2600006)
4. For each of the 3 IDs:
   • Checks format (YUG + 5 digits)
   • Searches database for user
   • If SPECIFIC event: Checks if member has registered AND paid for this event
   • If GENERAL event: Checks if member has General Pass valid for this event date
   • Validates each member

Bot sends:

┌────────────────────────────────────────┐
│  ⚠️ Extra IDs detected                 │
│                                        │
│  Team size is 4 members.              │
│  You sent 5 IDs. Only considering     │
│  first 3 members.                     │
│                                        │
│  Validating: YUG2600002, YUG2600003,      │
│  YUG2600004                             │
└────────────────────────────────────────┘

Then bot validates each member:

Scenario 1: All members valid (SPECIFIC Event)

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Rahul Kumar (YUG2600002)             │
│     Status: ✅ Registered & Paid      │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ✅ Priya Sharma (YUG2600003)            │
│     Status: ✅ Registered & Paid      │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ✅ Amit Patel (YUG2600004)              │
│     Status: ✅ Registered & Paid      │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  🎉 Team Validated Successfully!       │
│                                        │
│  Event: Code Marathon                 │
│  Team Size: 4 members                 │
│                                        │
│  Team Members:                        │
│  1. You (Leader) - ✅ Paid            │
│  2. Rahul Kumar - ✅ Paid             │
│  3. Priya Sharma - ✅ Paid            │
│  4. Amit Patel - ✅ Paid              │
│                                        │
│  All members have paid! Creating team...│
└────────────────────────────────────────┘

Bot then sends:

┌────────────────────────────────────────┐
│  ✅ Team Created Successfully!         │
│                                        │
│  Team ID: TEAM001                     │
│  Event: Code Marathon                 │
│                                        │
│  All team members have been notified. │
│                                        │
│  Event Details:                       │
│  📅 Feb 15, 2026                      │
│  ⏰ 9:00 AM                           │
│  📍 CSE Lab                           │
│                                        │
│  All the best! 🚀                     │
│                                        │
│  [🏠 Main Menu]                       │
│  [👥 My Teams]                        │
└────────────────────────────────────────┘

What happens internally:

1. Creates team record in database
2. Links all 4 members to team
3. Sends WhatsApp notification to all team members
4. Updates registrations with team_id
5. State returns to idle

Scenario 2: Some members haven’t paid (SPECIFIC Event)

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Rahul Kumar (YUG2600002)             │
│     Status: ✅ Registered & Paid      │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ❌ Priya Sharma (YUG2600003)            │
│     Status: ⚠️ Not Registered/Paid    │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ❌ Amit Patel (YUG2600004)              │
│     Status: ⚠️ Not Registered/Paid    │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ⚠️ Team Creation Failed               │
│                                        │
│  The following members have not        │
│  registered or paid for this event:   │
│                                        │
│  • YUG2600003 (Priya Sharma)            │
│  • YUG2600004 (Amit Patel)              │
│                                        │
│  Please ask them to:                  │
│  1. Message this WhatsApp bot         │
│  2. Browse Events → Code Marathon     │
│  3. Register and complete payment     │
│                                        │
│  After they complete payment, you can │
│  create the team via "My Teams" menu. │
│                                        │
│  [🏠 Main Menu]                       │
│  [👥 My Teams]                        │
└────────────────────────────────────────┘

What happens internally:

• No team created
• User registration remains individual
• User can retry later via My Teams
• State returns to idle

Scenario 3: General Event - Members need General Pass

If this is a GENERAL event:

Bot checks if all members have General Pass valid for event date.

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Rahul Kumar (YUG2600002)             │
│     Status: ✅ Has General Pass        │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ❌ Priya Sharma (YUG2600003)            │
│     Status: ⚠️ No General Pass         │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│  ⚠️ Team Creation Failed               │
│                                        │
│  The following members don't have     │
│  General Event Pass for this date:    │
│                                        │
│  • YUG2600003 (Priya Sharma)            │
│                                        │
│  Please ask them to:                  │
│  1. Message this WhatsApp bot         │
│  2. Buy General Event Pass (₹2999)    │
│  3. Then register for this event      │
│                                        │
│  After they purchase, you can create  │
│  the team via "My Teams" menu.        │
│                                        │
│  [🏠 Main Menu]                       │
│  [👥 My Teams]                        │
└────────────────────────────────────────┘

What happens internally:

• No team created
• User registration remains individual
• User can retry later via My Teams
• State returns to idle

💳 PAYMENT FLOW (Enhanced with Razorpay)

Step 8A: Payment Flow (Specific Event / Workshop)

After user clicks “Proceed to Payment”:

Bot sends:

┌────────────────────────────────────────┐
│  💳 Payment Link Generated             │
│                                        │
│  Event: Code Marathon                 │
│  Amount: ₹200                         │
│  Registration ID: REG123456           │
│                                        │
│  Click to pay securely:               │
│  https://yugam.in/pay/REG123456       │
│                                        │
│  • Powered by Razorpay                │
│  • 100% secure payment                │
│  • Instant confirmation               │
│                                        │
│  Link expires in 24 hours.            │
└────────────────────────────────────────┘

What happens internally:

1. Bot generates Razorpay payment order
2. Creates payment link: https://yugam.in/pay/{registration_id}
3. State changes to awaiting_payment
4. Registration marked as “Pending Payment”

User Journey:

1. User clicks payment link
2. Opens Yugam website payment page
3. Sees order summary:
   • Event name
   • Amount
   • Breakdown
4. Enters card/UPI/netbanking details
5. Completes payment via Razorpay
6. After payment, Razorpay redirects to:
   • Success: https://yugam.in/payment/success?registration_id=REG123456
   • Failure: https://yugam.in/payment/failed?registration_id=REG123456

Razorpay Webhook Flow:

1. Payment succeeds on Razorpay
2. Razorpay sends webhook to: https://api.yugam.in/api/v1/payments/razorpay-webhook
3. Backend verifies webhook signature
4. Backend updates registration:
   • payment_status → “paid”
   • registration_status → “confirmed”
   • payment_id → Razorpay payment ID
   • paid_at → Current timestamp
5. Backend triggers WhatsApp confirmation message

After successful payment (via webhook):

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Payment Successful!                │
│                                        │
│  Event: Code Marathon                 │
│  Amount Paid: ₹200                    │
│  Payment ID: pay_MfG123abc456         │
│                                        │
│  Registration Status: ✅ Confirmed    │
│                                        │
│  Your Yugam ID: YUG2600001              │
│  Registration ID: REG123456           │
│                                        │
│  Event Details:                       │
│  📅 Feb 15, 2026                      │
│  ⏰ 9:00 AM                           │
│  📍 CSE Lab                           │
│                                        │
│  Receipt sent to your email.          │
│                                        │
│  See you at the event! 🎉            │
│                                        │
│  [🏠 Main Menu]                       │
│  [📝 My Registrations]                │
└────────────────────────────────────────┘

What happens internally:

• Registration status → “Confirmed”
• Email confirmation sent
• SMS confirmation sent (optional)
• User can view in “My Registrations”
• State returns to idle

Step 8B: Payment Flow (General Event Pass)

After user clicks “Buy General Pass”:

Bot sends:

┌────────────────────────────────────────┐
│  💳 Payment Link Generated             │
│                                        │
│  Product: General Event Pass          │
│  Amount: ₹2999                        │
│  Pass ID: GPASS123456                 │
│                                        │
│  Click to pay securely:               │
│  https://yugam.in/pay/GPASS123456     │
│                                        │
│  • Powered by Razorpay                │
│  • Unlimited access to all general    │
│    events (Feb 15-18, 2026)           │
│  • Instant QR code delivery           │
│                                        │
│  Link expires in 24 hours.            │
└────────────────────────────────────────┘

After successful payment (via webhook):

Bot sends:

┌────────────────────────────────────────┐
│  🎉 General Pass Activated!            │
│                                        │
│  Pass ID: GPASS123456                 │
│  Valid: Feb 15-18, 2026               │
│  Amount Paid: ₹2999                   │
│                                        │
│  Your all-access QR code:             │
│  [QR Code Image Sent]                 │
│                                        │
│  ✅ You can now attend:               │
│  • All General Events                 │
│  • Opening & Closing Ceremonies       │
│  • Cultural Activities                │
│                                        │
│  Register for individual general      │
│  events via the bot - no payment      │
│  needed!                              │
│                                        │
│  Have an amazing Yugam 2026! 🎊       │
│                                        │
│  [🏠 Main Menu]                       │
│  [📅 Browse Events]                   │
└────────────────────────────────────────┘

Bot also sends QR code image with Pass ID embedded.

What happens internally:

• Creates general_pass registration
• Generates unique QR code
• Stores QR in database
• Sends QR image via WhatsApp
• Email confirmation with QR
• State returns to idle

Razorpay Webhook Setup (Technical Details)

Webhook URL: https://api.yugam.in/api/v1/payments/razorpay-webhook

Events to Subscribe:

• payment.captured (payment successful)
• payment.failed (payment failed)
• order.paid (order completed)

Webhook Handler Logic:

1. Receive webhook POST request
2. Verify signature using Razorpay webhook secret:

   signature = HMAC-SHA256(webhook_secret, request_body)
   if signature != request.headers['X-Razorpay-Signature']:
       return 401 Unauthorized
   

3. Parse event type
4. Extract payment details
5. Find registration by order_id or registration_id
6. Update database
7. Trigger WhatsApp message
8. Send email
9. Return 200 OK

Webhook Response Time: < 2 seconds (must respond quickly to Razorpay)

🎓 OPTION 2: BROWSE WORKSHOPS

Exactly same flow as Events, but for workshops:

1. Categories might be different (Technical, Creative, Business, etc.)
2. Workshops usually individual (no teams)
3. Different database table but same process

🎁 OPTION 3: COMBO OFFERS (REMOVED)

Note: Combo offers have been removed. Users should either:

• Purchase specific events individually
• Purchase the General Event Pass for unlimited access to general events

🎟️ OPTION 4: BUY GENERAL EVENT PASS (NEW)

What is General Event Pass?

• One pass = Entry to ALL events (like a festival pass)
• User doesn’t register for specific events
• Can attend any event they want

Step 1: User Clicks “Buy General Pass”

Bot sends:

┌────────────────────────────────────────┐
│  🎟️ General Event Pass                │
│                                        │
│  Get unlimited access to ALL Yugam    │
│  2026 events!                         │
│                                        │
│  What's Included:                     │
│  ✓ All Technical Events               │
│  ✓ All Cultural Events                │
│  ✓ All Sports Events                  │
│  ✓ All Workshops                      │
│  ✓ Opening & Closing Ceremonies       │
│                                        │
│  Price: ₹2999                         │
│  (Save over ₹5000!)                   │
│                                        │
│  Valid: Feb 15-18, 2026               │
│                                        │
│  [🛒 Buy Now]                         │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

What happens internally:

• State changes to buying_general_pass

Step 2: User Clicks “Buy Now”

If NOT logged in:

• Shows login message (same as events)

If logged in:

Bot sends:

┌────────────────────────────────────────┐
│  ✅ Confirm Purchase                   │
│                                        │
│  General Event Pass                   │
│  Price: ₹2999                         │
│                                        │
│  This gives you access to ALL events. │
│                                        │
│  Proceed with purchase?               │
│                                        │
│  [✅ Confirm]  [❌ Cancel]            │
└────────────────────────────────────────┘

If user clicks “Confirm”:

1. Bot creates “General Pass” registration in database
   • Type: General Pass
   • Valid dates: Festival dates
   • User: YUG2600001
2. Bot generates payment link
3. Bot sends payment message (₹2999)

After payment:

┌────────────────────────────────────────┐
│  🎉 General Pass Activated!            │
│                                        │
│  Your all-access pass is ready!       │
│                                        │
│  Pass ID: GP26001                     │
│  Valid: Feb 15-18, 2026               │
│                                        │
│  Show this at any event entrance:     │
│  [QR Code Image]                      │
│                                        │
│  You can now attend ANY event         │
│  without individual registration!     │
│                                        │
│  Have an amazing Yugam 2026! 🎊       │
└────────────────────────────────────────┘

What happens internally:

• User marked as “General Pass Holder”
• QR code generated with Pass ID
• Can check-in at any event
• No need to register for individual events

📝 OPTION 5: MY REGISTRATIONS

Step 1: User Clicks “My Registrations”

If NOT logged in:

• Shows login message

If logged in:

What bot does:

1. Searches database for all registrations by user YUG2600001
2. Finds, for example: 3 registrations
3. Formats them into list

Bot sends:

┌────────────────────────────────────────┐
│  📝 Your Registrations                 │
│                                        │
│  1. Code Marathon                     │
│     Status: ✅ Confirmed              │
│     Payment: ✅ Paid                  │
│                                        │
│  2. AI Workshop                       │
│     Status: ⏳ Pending                │
│     Payment: ❌ Pending               │
│                                        │
│  3. Dance Competition                 │
│     Status: ✅ Confirmed              │
│     Payment: ✅ Paid                  │
│                                        │
│  What next?                           │
│                                        │
│  [🏠 Main Menu]                       │
│  [📅 Browse Events]                   │
└────────────────────────────────────────┘

What happens internally:

• State changes to my_registrations
• Shows all registrations (paid and unpaid)

If user has pending payments:

• Bot can send reminders
• Show payment links again

👥 OPTION 6: MY TEAMS

Step 1: User Clicks “My Teams”

What bot does:

1. Finds all teams where user is leader or member
2. Gets team details from database
3. Checks if user is eligible to create teams (paid for team events but no team yet)

Scenario A: User has teams AND can create more

Bot sends:

┌────────────────────────────────────────┐
│  👥 Your Teams                         │
│                                        │
│  Existing Teams:                      │
│                                        │
│  Team 1: Code Warriors (Leader)       │
│  Event: Code Marathon                 │
│  Members: 4                           │
│  • You                                │
│  • Rahul Kumar                        │
│  • Priya Sharma                       │
│  • Amit Patel                         │
│  Status: ✅ Confirmed                 │
│                                        │
│  Team 2: Dance Squad (Member)         │
│  Event: Dance Competition             │
│  Leader: Amit Patel                   │
│  Members: 6 people                    │
│  Status: ✅ Confirmed                 │
│                                        │
│  ──────────────────────────────────── │
│                                        │
│  ✨ You can create teams for:         │
│                                        │
│  • Hackathon 24hrs                    │
│                                        │
│  Would you like to create a team?     │
│                                        │
│  [✅ Create Team]                     │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

What happens internally:

• State changes to my_teams
• Bot identifies paid team events without teams
• Shows both existing teams and creation options

If user clicks “Create Team”:

What bot does:

1. Checks how many events user is eligible for
2. If multiple events → Shows list to select
3. If one event → Proceeds directly

Bot sends (if multiple eligible events):

┌────────────────────────────────────────┐
│  👥 Select Event for Team              │
│                                        │
│  Choose which event you want to       │
│  create a team for:                   │
│  [View Events ▼]                      │
│                                        │
│  When clicked, shows:                 │
│  • Hackathon 24hrs (Feb 16)           │
│  • Robotics Challenge (Feb 18)        │
└────────────────────────────────────────┘

User selects “Hackathon 24hrs”

Bot sends:

┌────────────────────────────────────────┐
│  👥 Create Team for Hackathon 24hrs    │
│                                        │
│  Team Size: 4 members (including you) │
│                                        │
│  You are the team leader.             │
│  You have already paid for this event.│
│                                        │
│  Please send Yugam IDs of your        │
│  3 team members separated by commas.  │
│                                        │
│  Example: YUG2600002, YUG2600003, YUG2600004│
│                                        │
│  ⚠️ Important: All members must have  │
│  registered and paid for this event.  │
└────────────────────────────────────────┘

What happens internally:

• State changes to collecting_team_members
• Bot saves selected event_id
• Bot waits for Yugam IDs

Then follows same validation flow as Step 7 above:

• User sends IDs
• Bot validates each member
• Bot checks payment/pass status
• Creates team if all valid
• Shows error if any member invalid

Scenario B: User has teams but NOT eligible to create more

Bot sends:

┌────────────────────────────────────────┐
│  👥 Your Teams                         │
│                                        │
│  Team 1: Code Warriors (Leader)       │
│  Event: Code Marathon                 │
│  Members: 4                           │
│  • You                                │
│  • Rahul Kumar                        │
│  • Priya Sharma                       │
│  • Amit Patel                         │
│  Status: ✅ Confirmed                 │
│                                        │
│  Team 2: Dance Squad (Member)         │
│  Event: Dance Competition             │
│  Leader: Amit Patel                   │
│  Members: 6 people                    │
│  Status: ✅ Confirmed                 │
│                                        │
│  You have no pending team events.     │
│                                        │
│  [🏠 Main Menu]                       │
│  [📅 Browse Events]                   │
└────────────────────────────────────────┘

What happens internally:

• State changes to my_teams
• Shows only existing teams
• No create team option (not eligible)

Scenario C: User has NO teams but IS eligible to create

Bot sends:

┌────────────────────────────────────────┐
│  👥 Your Teams                         │
│                                        │
│  You haven't created any teams yet.   │
│                                        │
│  ──────────────────────────────────── │
│                                        │
│  ✨ You can create teams for:         │
│                                        │
│  • Code Marathon (Feb 15)             │
│  • Hackathon 24hrs (Feb 16)           │
│                                        │
│  Would you like to create a team?     │
│                                        │
│  [✅ Create Team]                     │
│  [🏠 Main Menu]                       │
└────────────────────────────────────────┘

What happens internally:

• Bot finds paid team events without teams
• Offers team creation
• If user proceeds → Same flow as above

Scenario D: User has NO teams and NOT eligible

Bot sends:

┌────────────────────────────────────────┐
│  👥 Your Teams                         │
│                                        │
│  You haven't joined or created any    │
│  teams yet.                           │
│                                        │
│  Register for team events to create   │
│  or join teams!                       │
│                                        │
│  [🏠 Main Menu]                       │
│  [📅 Browse Events]                   │
└────────────────────────────────────────┘

What happens internally:

• State changes to my_teams
• No teams found
• No eligible team events
• User directed to browse events

Eligibility Criteria for Team Creation

User is eligible to create a team if:

1. For Specific Event:

   • User has registered for the event
   • User has paid for the event (payment_status = ‘paid’)
   • Event is a team event (team_size > 1)
   • User doesn’t already have a team for this event
   • Event hasn’t happened yet

2. For General Event:

   • User has General Event Pass valid for event date
   • User has registered for the event
   • Event is a team event (team_size > 1)
   • User doesn’t already have a team for this event
   • Event hasn’t happened yet

Bot Query Logic:

SELECT events WHERE:
  - event has registration by user
  - payment_status = 'paid'
  - team_size > 1
  - user NOT in any team for this event
  - event_date >= today

👤 OPTION 7: MY PROFILE

Step 1: User Clicks “My Profile”

If NOT logged in:

• Shows login message

If logged in:

What bot does:

1. Gets user details from database

Bot sends:

┌────────────────────────────────────────┐
│  👤 Your Profile                       │
│                                        │
│  Name: Rajesh Kumar                   │
│  Yugam ID: YUG2600001                   │
│  Email: rajesh@example.com            │
│  Phone: 9876543210                    │
│                                        │
│  College: PSG College of Technology   │
│  Department: Computer Science         │
│  Year: 2nd Year                       │
│                                        │
│  What next?                           │
│                                        │
│  [🏠 Main Menu]                       │
│  [📝 My Registrations]                │
└────────────────────────────────────────┘

What happens internally:

• State changes to my_profile
• Shows current user information

🔐 LOGIN FLOW (Separate from Main Bot)

This happens when user clicks “Continue with WhatsApp” on website.

Step 1: User on Website Login Page

Website shows:
┌────────────────────────────────────────┐
│  Login to Yugam 2026                  │
│                                        │
│  [🔵 Continue with Google]            │
│  [🔵 Continue with Microsoft]         │
│  [🟢 Continue with WhatsApp]          │
└────────────────────────────────────────┘

User clicks “Continue with WhatsApp”

Step 2A: Phone Number Modal (Desktop/Laptop Only)

This step only appears when accessing from Desktop/Laptop

Website shows popup:
┌────────────────────────────────────────┐
│  Enter Your Phone Number              │
│                                        │
│  We'll send you a WhatsApp message    │
│  to verify your identity.             │
│                                        │
│  +91 [__________]                     │
│                                        │
│  [Cancel]  [Continue]                 │
└────────────────────────────────────────┘

User enters: 9876543210

What happens internally:

• Website detects device type (desktop)
• Shows phone input modal
• User enters phone number
• After entering → Proceeds to Step 3

Step 2B: Direct WhatsApp (Mobile Only)

This happens when accessing from Mobile Device

What happens:

• User clicks “Continue with WhatsApp”
• Website detects mobile device
• Directly opens WhatsApp with pre-filled message
• No phone number input needed!

What happens internally:

if (isMobile) {
  // Direct WhatsApp link
  window.location.href = 'https://wa.me/919876543210?text=Hi%20Yugam%2C%20Help%20me%20Sign%20in!'
} else {
  // Show phone input modal
  showPhoneModal()
}

Step 3: Redirect to WhatsApp

What happens:

1. Website saves phone number
2. Website opens WhatsApp with pre-filled message
3. WhatsApp opens with text: “Hi Yugam, Help me Sign in!”

User sends the message

Step 4: Bot Receives Message

What bot does:

1. Checks if message contains keywords: “hi yugam”, “sign in”, “login”
2. If yes, generates login token (valid 5 minutes)
3. Creates login link: yugam.in/auth/whatsapp/verify?token=abc123

Bot sends:

┌────────────────────────────────────────┐
│  Welcome to Yugam 2026! 🎉            │
│                                        │
│  Click to login:                      │
│  https://yugam.in/         │
│  auth/whatsapp/verify?token=abc123    │
│                                        │
│  ✓ Track your registrations           │
│  ✓ Access exclusive deals             │
│                                        │
│  Link expires in 5 minutes.           │
└────────────────────────────────────────┘

Step 5: User Clicks Link

What happens:

1. Opens website verification page
2. Website checks token in database
3. Token found, valid, not expired

If user exists in database:

Website shows:
┌────────────────────────────────────────┐
│  ✅ Login Successful!                  │
│                                        │
│  Redirecting to dashboard...          │
└────────────────────────────────────────┘

• User logged in
• Redirects to dashboard

If user is NEW:

Website shows:
┌────────────────────────────────────────┐
│  👋 Welcome! Let's create your account │
│                                        │
│  Redirecting to registration...       │
└────────────────────────────────────────┘

• Redirects to registration page
• Phone number already filled (verified)
• User fills rest of details
• Creates account
• Logs in automatically

🤖 BOT STATES EXPLAINED

What are “States”?

States are like memory - bot remembers what conversation stage you’re at.

Why States Matter?

Example 1: Registration Flow

• User at collecting_email state
• Bot expects email address
• If user sends "rajesh@gmail.com" → Validates and proceeds
• If user sends “menu” → Asks “Complete registration first or type ‘cancel’”

Example 2: Team Formation

• User is at team_formation state
• Bot expects Yugam IDs like “YUG2600001, YUG2600002”
• If user sends “menu”, bot goes back to idle
• If user sends IDs, bot processes them

Without states:

• Bot wouldn’t know what user wants
• Every message would be confusing
• Like having amnesia in every conversation

🔄 COMPLETE USER JOURNEY EXAMPLES

Journey 0: New User Registration (Complete Flow)

1. User sends "Hi" on WhatsApp for FIRST TIME
   → Bot: Checks database → User NOT found
   → Bot: "Welcome! You haven't registered yet. Let's create your account!"

2. Bot: "What is your full name?"
   → User: "Rajesh Kumar"
   → Bot: Saves name

3. Bot: "What is your Gmail ID?"
   → User: "rajesh@gmail.com"
   → Bot: Validates format ✅
   → Bot: Saves email

4. Bot: Shows college list from database (ALL colleges with search)
   → User: Types "PSG" in search
   → Filtered list shows PSG colleges
   → User: Selects "PSG College of Technology"
   → Bot: Saves college_id = 5

5. Bot: Shows department list from database (ALL departments with search)
   → User: Types "Computer" in search
   → Filtered list shows CS-related departments
   → User: Selects "Computer Science Engineering"
   → Bot: Saves department_id = 1

6. Bot: Shows year options
   → User: Selects "2nd Year"
   → Bot: Saves year

7. Bot: Shows summary of all details
   → "Is this correct? [Confirm] [Edit]"
   → User: Clicks "Confirm"

8. Bot: Creates user account immediately
   → Bot: Generates Yugam ID: YUG2600001
   → Bot: "Registration successful! Your Yugam ID: YUG2600001"

9. Bot: Shows Main Menu
   → User can now browse events, workshops, etc.

DONE! User registered and ready to participate.

Journey 1: Existing User Returns

1. User sends "Hi" on WhatsApp (already registered before)
   → Bot: Checks database → User FOUND
   → Bot: "Hi Rajesh Kumar! Welcome back to Yugam 2026!"
   → Bot: Shows Yugam ID: YUG2600001

2. Bot: Shows Main Menu immediately
   → No registration needed
   → User can browse and register for events

DONE! Quick access for returning users.

Journey 2: Team Event Registration (New Flow)

1. User sends "Hi" on WhatsApp
   → Bot: Welcome menu

2. User clicks "Browse Events"
   → Bot: Shows categories (General/Specific/All)

3. User selects "Specific Events"
   → Bot: Shows 5 specific events

4. User selects "Code Marathon" (team event)
   → Bot: Shows event details with Register button

5. User clicks "Register Now"
   → Bot: Checks if event has before-payment form
   → No form → Proceeds to registration

6. Bot: "Registration created! Proceed to payment?"
   → User clicks "Proceed to Payment"

7. Bot sends Razorpay payment link (₹200)
   → User clicks link, pays on website

8. Payment successful → Razorpay webhook triggers
   → Bot: "✅ Payment successful!"

9. Bot checks team_size > 1 (it's 4)
   → Bot: "This is a team event. Create team?"

10. User clicks "Yes, Create Team"
    → Bot: "Send 3 Yugam IDs (team size is 4)"

11. User sends "YUG2600002, YUG2600003, YUG2600004"
    → Bot validates each member:
    → Checks if they registered & paid for Code Marathon

12. All 3 members have paid:
    → Bot: "✅ Team validated! Creating team..."

13. Bot creates team in database
    → Bot: "🎉 Team created! Team ID: TEAM001"
    → All 4 members get WhatsApp notification

DONE! User registered individually, paid, then created team.

Journey 3: Existing User Quick Registration

1. User (already logged in before) sends "Hi"
   → Bot: Welcome menu

2. User clicks "Browse Workshops"
   → Bot: Categories

3. User selects "AI Workshop"
   → Bot: Workshop details

4. User clicks "Register Now"
   → Bot: "Confirm ₹300?" (individual, no team needed)

5. User clicks "Confirm"
   → Bot: Payment link

6. User pays
   → Bot: "✅ Registration complete!"

DONE! Quick registration in 6 steps.

Journey 4: Buying General Pass

1. User sends "Hi"
   → Bot: Welcome menu

2. User clicks "Buy General Pass"
   → Bot: Shows pass details (₹2999, all events)

3. User clicks "Buy Now"
   → Bot: "Confirm purchase?"

4. User clicks "Confirm"
   → Bot: Payment link

5. User pays via Razorpay
   → Webhook: Payment successful
   → Bot: "🎉 Pass activated!" + QR code sent

DONE! User can now attend all general events.

Journey 5: Creating Team Later via “My Teams”

1. User already paid for "Hackathon 24hrs" yesterday
   → But didn't create team yet

2. User sends "Hi"
   → Bot: Welcome menu

3. User clicks "My Teams"
   → Bot checks eligibility
   → User has paid for Hackathon (team event)
   → No team created yet

4. Bot shows:
   → "You can create teams for: Hackathon 24hrs"
   → [Create Team] button

5. User clicks "Create Team"
   → Bot: "Send 3 Yugam IDs"

6. User sends "YUG2600002, YUG2600003, YUG2600004, YUG2600005"
   → Bot: "Team size is 4, taking only first 3 IDs"

7. Bot validates:
   → YUG2600002: ✅ Paid
   → YUG2600003: ❌ Not paid
   → YUG2600004: ✅ Paid

8. Bot: "Team creation failed! YUG2600003 hasn't paid."
   → "Ask them to register and pay first."

9. User contacts Priya (YUG2600003)
   → Priya registers and pays

10. User goes to "My Teams" again
    → Clicks "Create Team" for Hackathon

11. User sends "YUG2600002, YUG2600003, YUG2600004"
    → Bot validates: All 3 have paid ✅

12. Bot: "🎉 Team created! Team ID: TEAM002"
    → All members notified

DONE! Team created successfully after all members paid.

📊 SPECIAL SCENARIOS

Scenario 1: Payment Pending Reminder

What happens:

• User registers but doesn’t pay
• After 24 hours, bot sends reminder

Bot sends:

┌────────────────────────────────────────┐
│  ⏰ Payment Reminder                   │
│                                        │
│  Your registration for Code Marathon  │
│  is pending payment.                  │
│                                        │
│  Complete payment to confirm:         │
│  [Payment Link]                       │
│                                        │
│  Registration expires in 24 hours.    │
└────────────────────────────────────────┘

Scenario 2: Event Day Reminder

What happens:

• Day before event, bot sends reminder to all registered users

Bot sends:

┌────────────────────────────────────────┐
│  ⏰ Event Tomorrow!                    │
│                                        │
│  Code Marathon is tomorrow!           │
│                                        │
│  📅 Date: Feb 15, 2026                │
│  ⏰ Time: 9:00 AM                     │
│  📍 Venue: CSE Lab                    │
│                                        │
│  Team:                                │
│  • You (Leader)                       │
│  • Rahul Kumar                        │
│  • Priya Sharma                       │
│                                        │
│  All the best! 🎉                    │
└────────────────────────────────────────┘

Scenario 3: Team Member Hasn’t Paid

User tries to create team but one member hasn’t paid:

1. User paid for Code Marathon
2. After payment, chooses to create team
3. Sends: YUG2600002, YUG2600003, YUG2600004
4. Bot checks each member:
   • YUG2600002: ✅ Paid
   • YUG2600003: ❌ Not paid
   • YUG2600004: ✅ Paid

Bot sends:

┌────────────────────────────────────────┐
│  ⚠️ Team Creation Failed               │
│                                        │
│  YUG2600003 (Priya Sharma) hasn't       │
│  registered or paid for this event.   │
│                                        │
│  Ask them to register and pay via     │
│  this WhatsApp bot.                   │
│                                        │
│  You can create the team later via    │
│  "My Teams" option after they pay.    │
└────────────────────────────────────────┘

What happens:

• User’s registration stays individual
• No team created yet
• User can retry after member pays

Scenario 4: User Sends Random Text

User sends: “What is the prize money?”

What bot does:

1. Checks current state
2. If in event_details state: Tries to answer about current event
3. If in idle state: Shows main menu

Bot sends:

┌────────────────────────────────────────┐
│  I don't understand that command.     │
│                                        │
│  Type "menu" for main menu or         │
│  "help" for assistance.               │
└────────────────────────────────────────┘

📊 WHATSAPP BUSINESS INBOX / CRM DASHBOARD

🎯 Overview

You can build a web-based chat dashboard to monitor and manage all WhatsApp bot conversations - similar to Interakt, WATI, or Zoko, but custom-built for Yugam.

What You Can Track:

• ✅ Who messaged the bot (all users)
• ✅ Complete conversation history per user
• ✅ Incoming + outgoing messages dynamically
• ✅ Timestamps and read receipts
• ✅ Agent/Bot replies
• ✅ User states and session data
• ✅ Registration status and payment tracking

Think of it as: WhatsApp Web for your bot + CRM features

🧠 The Concept (High Level)

Core Idea:
Every time a message is sent or received via WhatsApp Cloud API:

1. 👉 Capture it in your backend
2. 👉 Store it in database
3. 👉 Display dynamically in web UI

Your backend becomes the system of record for all conversations.

🔄 Data Flow Diagram

┌──────────┐         ┌──────────────┐         ┌─────────────┐
│   User   │ ─────→  │   WhatsApp   │ ─────→  │ Your Server │
│          │         │   Cloud API  │         │  (Backend)  │
└──────────┘         └──────────────┘         └─────────────┘
                                                      │
                                                      │ Saves
                                                      ↓
                                               ┌─────────────┐
                                               │  Database   │
                                               │  Messages   │
                                               └─────────────┘
                                                      │
                                                      │ Fetches
                                                      ↓
                                               ┌─────────────┐
                                               │   Web UI    │
                                               │  Dashboard  │
                                               └─────────────┘

Detailed Flow:

1. Incoming Message:

   User sends "Hi" on WhatsApp
   → Meta Cloud API receives it
   → Sends to your webhook
   → Your server processes & saves to database
   → Bot logic responds
   → Response also saved to database
   → Dashboard UI auto-updates (real-time)
   

2. Outgoing Message (Agent Reply):

   Admin types reply in dashboard
   → Server sends via WhatsApp Cloud API
   → Saves outgoing message to database
   → WhatsApp delivers to user
   → Status updates shown in UI (sent → delivered → read)
   

🧩 What’s Needed (Components)

1. WhatsApp Webhooks

• Configure in Meta Developer Console
• Captures incoming messages, status updates, interactive replies
• Stores everything in database automatically

2. Database Tables

Two main tables needed:

Table: tbl_whatsapp_messages

• Stores every message (incoming and outgoing)
• Fields: user phone, message content, timestamp, direction, status, bot state

Table: tbl_whatsapp_sessions

• Tracks conversation sessions per user
• Fields: session ID, last activity, assigned agent, tags

3. Backend API

API endpoints to:

• Get list of all conversations
• Get chat history for specific user
• Send message from dashboard
• Get analytics (total chats, pending payments, etc.)

4. Frontend Dashboard

Web UI showing:

• Left panel: List of all users who messaged
• Right panel: Chat thread for selected user
• User info sidebar: Registrations, teams, current bot state

📺 Dashboard Layout (Visual)

┌─────────────────────────────────────────────────────────────┐
│  🏠 Yugam WhatsApp Dashboard           [Profile] [Logout]   │
├──────────────────┬──────────────────────────────────────────┤
│  Conversations   │  Chat: Rajesh Kumar (+919876543210)     │
│  ─────────────   │  ───────────────────────────────────────│
│                  │                                          │
│ 🔍 Search...     │  [User]                            10:30 │
│                  │  Hi                                      │
│ ┌──────────────┐ │                                          │
│ │ Rajesh Kumar │ │                              [Bot] 10:30 │
│ │ YUG2600001   ● │ │  Welcome to Yugam 2026!                 │
│ │ Hi...        │ │  What would you like to do?             │
│ │ 2 mins ago   │ │                                          │
│ └──────────────┘ │  [Browse Events] [Workshops]             │
│                  │                                          │
│ ┌──────────────┐ │  [User]                            10:32 │
│ │ Priya Sharma │ │  Browse Events                           │
│ │ YUG2600002     │ │                                          │
│ │ Payment pend │ │                              [Bot] 10:32 │
│ │ 5 mins ago   │ │  Select category: General/Specific       │
│ └──────────────┘ │                                          │
│                  │  [User]                            10:33 │
│ ┌──────────────┐ │  Specific Events                         │
│ │ Amit Patel   │ │                                          │
│ │ YUG2600003     │ │                              [Bot] 10:33 │
│ │ Team created │ │  Here are the specific events...         │
│ │ 1 hour ago   │ │                                          │
│ └──────────────┘ │  ─────────────────────────────────────── │
│                  │  💬 Type message...         [Send]       │
│ [Filters ▼]      │                                          │
├──────────────────┴──────────────────────────────────────────┤
│  📊 1,250 conversations  |  🤖 Bot Active  |  ⏱ Avg: 2m    │
└─────────────────────────────────────────────────────────────┘

Left Panel - Conversation List:

• Shows all users who messaged the bot
• Each card shows:
  • User name and Yugam ID
  • Last message preview
  • Time ago
  • Unread count (if any)
  • Online status (● green dot)
• Searchable and filterable

Right Panel - Chat Thread:

• Shows complete message history
• Incoming messages (user) on left
• Outgoing messages (bot/agent) on right
• Timestamps for each message
• Status indicators (sent ✓, delivered ✓✓, read ✓✓ blue)
• Interactive message buttons visible

Bottom - Message Input:

• Type and send replies manually
• Switch between bot mode and agent mode
• Emoji support

📊 User Info Sidebar

┌────────────────────┐
│ User Info          │
├────────────────────┤
│ 👤 Rajesh Kumar    │
│ 🆔 YUG2600001        │
│ 📱 +9198765...     │
│                    │
│ Current State:     │
│ 🔵 idle            │
│                    │
│ Last Activity:     │
│ ⏰ 2 minutes ago   │
│                    │
│ Tags:              │
│ 🏷️ [new_user]     │
│ 🏷️ [paid]         │
│                    │
│ ──────────────────│
│ 📝 Registrations   │
│                    │
│ ✅ Code Marathon   │
│    Paid: ₹200     │
│    Team: TEAM001   │
│                    │
│ ✅ AI Workshop     │
│    Paid: ₹300     │
│    Individual      │
│                    │
│ ⏳ Hackathon       │
│    Payment Pending │
│                    │
│ ──────────────────│
│ [View Full Profile]│
└────────────────────┘

This sidebar shows at-a-glance:

• Who the user is
• What state bot conversation is in
• All their registrations
• Payment status
• Team memberships
• Quick actions

🎨 Conversation Flow Diagram

┌─────────────────────────────────────────────────────┐
│                    User Journey                     │
└─────────────────────────────────────────────────────┘

User Message         Bot Response          Dashboard Shows
────────────         ────────────          ───────────────

"Hi" ──────────→  [Processing] ────────→  📱 New message
                       │                   from +9198765...
                       ↓
                  Welcome Menu ─────────→  💬 Bot replied
                  [Buttons]                with main menu
                       ↓
Click "Browse    [Processing] ────────→  🔵 State changed:
Events" ────────→                         browsing_events
                       ↓
                  Event List ───────────→ 💬 Bot sent
                  [Categories]             event categories
                       ↓
Select           Event Details ────────→  💬 User viewing
"Code Marathon"→ [Register Now]           Code Marathon
                       ↓
Click            Payment Link ─────────→  ⏳ State:
"Register" ─────→                         awaiting_payment
                       ↓
Payment          Success! ─────────────→  ✅ Payment confirmed
Complete                                   Dashboard updates

📈 Analytics Dashboard

Along with conversations, you can show:

┌──────────────────────────────────────────┐
│         📊 Bot Analytics                 │
├──────────────────────────────────────────┤
│                                          │
│  Total Conversations:  1,250            │
│  Active Today:         87               │
│  Pending Payments:     23               │
│                                          │
│  ────────────────────────────────────   │
│                                          │
│  By Bot State:                          │
│    • Idle:              500             │
│    • Browsing Events:   45              │
│    • Awaiting Payment:  23              │
│    • Team Formation:    12              │
│                                          │
│  ────────────────────────────────────   │
│                                          │
│  Response Time:                         │
│    Average: 2m 15s                      │
│                                          │
│  ────────────────────────────────────   │
│                                          │
│  Popular Events:                        │
│    1. Code Marathon (145 registrations) │
│    2. AI Workshop (98 registrations)    │
│    3. Hackathon (76 registrations)      │
│                                          │
└──────────────────────────────────────────┘

⭐ Features You Can Have

Basic Features (MVP):

• ✅ View all conversations dynamically
• ✅ Real-time message updates
• ✅ Search users by name/phone/Yugam ID
• ✅ Filter by bot state (idle, browsing, payment pending)
• ✅ Send manual replies as agent

Advanced Features:

• 🎯 Agent Assignment: Assign conversations to specific admins
• 🏷️ Tags: Label users (VIP, pending payment, team leader, etc.)
• 📊 Analytics: Conversion rates, popular events, response times
• 🔔 Notifications: Alert when new message arrives
• 📝 Quick Replies: Save common responses as templates
• 🤖 Bot/Agent Toggle: Pause bot, reply manually
• 📈 Journey Tracking: See path user took through bot
• 📤 Export: Download chats as CSV/PDF
• 🔍 Advanced Search: By event, date range, registration status
• 📱 Mobile Responsive: Manage on phone
• 👥 Multi-agent: Multiple admins online simultaneously

🔐 Important Notes

✅ This Works With:

• WhatsApp Cloud API (Meta’s official API)
• Official Business Service Providers (BSPs)

❌ Does NOT Work With:

• WhatsApp Web automation (banned by WhatsApp)
• Unofficial libraries
• Personal WhatsApp accounts

Security:

• Dashboard requires admin authentication
• All data encrypted
• Webhook signature verification
• HTTPS only

⏰ How Messages Update Dynamically

Real-time Updates:
When a new message arrives:

1. Webhook receives it instantly
2. Saves to database
3. WebSocket pushes update to dashboard
4. UI updates without page refresh
5. Admin sees new message in < 1 second

Technology:

• WebSocket (Socket.io) for real-time
• Or polling every 5-10 seconds (simpler but slower)

🎯 What This Gives You

For Admins:

• 👀 See every conversation happening live
• 🛠️ Jump in when bot needs help
• 📊 Track how users navigate bot
• 💰 Monitor payment issues in real-time
• 📞 Provide personalized support
• 📈 Understand user behavior

For Users:

• No change - they just use WhatsApp normally
• But can get human support if needed
• Faster resolution of issues

💡 Summary

You can build a dynamic web dashboard that shows:

• ✅ All WhatsApp conversations in one place
• ✅ Messages updating in real-time
• ✅ Complete history per user
• ✅ User’s registration status, teams, payments
• ✅ Bot state and journey tracking
• ✅ Agent reply capability
• ✅ Analytics and insights

Key Idea: Every message (in and out) is captured and stored, then displayed dynamically in a chat interface similar to WhatsApp Web.

🎯 SUMMARY: Complete Flow in One Page

USER SENDS "Hi"
    ↓
┌─────────────────────┐
│  Check if User      │
│  Exists in Database │
└─────────────────────┘
    ↓
    ├─→ [User Exists]
    │       ↓
    │   Show Personalized Welcome
    │   "Hi <Name>! Welcome back..."
    │       ↓
    │   MAIN MENU (Go to below)
    │
    └─→ [New User]
            ↓
        ┌──────────────────┐
        │ REGISTRATION     │
        │ FLOW             │
        └──────────────────┘
            ↓
        Ask Name
            ↓
        Ask Gmail ID
            ↓
        Show College List (ALL from DB + search)
        User selects
            ↓
        Show Department List (ALL from DB + search)
        User selects
            ↓
        Ask Year of Study
            ↓
        Show Summary
        User confirms
            ↓
        Create Account Immediately
            ↓
        Generate Yugam ID
            ↓
        Show Success Message
            ↓
        ┌────────────────────┐
        │  MAIN MENU         │
        │  (After Login/Reg) │
        └────────────────────┘
    ↓
    ├─→ Browse Events
    │       ↓
    │   Select Type (General/Specific/All)
    │       ↓
    │   Select Event
    │       ↓
    │   View Details
    │       ↓
    │   [If General Event]
    │       ↓
    │   Check for General Pass
    │       ├─→ Pass Exists → Register (No Payment)
    │       └─→ No Pass → Offer to Buy Pass
    │       ↓
    │   [If Specific Event]
    │       ↓
    │   Register Now
    │       ↓
    │   Check for Before-Payment Form
    │       ├─→ Form Exists → Collect Answers
    │       └─→ No Form → Continue
    │       ↓
    │   Create Registration Record
    │       ↓
    │   [If Individual Event]
    │       ↓
    │   Proceed to Payment
    │       ↓
    │   [If Team Event]
    │       ↓
    │   Add Team Members
    │       ↓
    │   Check All Members Paid
    │       ↓
    │   Confirm Team
    │       ↓
    │   [Always]
    │       ↓
    │   Razorpay Payment
    │       ↓
    │   Webhook → Update DB
    │       ↓
    │   Send Confirmation
    │       ↓
    │   ✅ Confirmed
    │
    ├─→ Browse Workshops
    │       ↓
    │   (Similar flow as Specific Events)
    │       ↓
    │   Check for Before-Payment Form
    │       ↓
    │   Payment → Confirmation
    │
    ├─→ Buy General Pass
    │       ↓
    │   View Pass Details
    │       ↓
    │   Confirm Purchase
    │       ↓
    │   Razorpay Payment (₹2999)
    │       ↓
    │   Webhook → Generate QR
    │       ↓
    │   Send QR Code via WhatsApp
    │       ↓
    │   ✅ Pass Activated
    │
    ├─→ My Registrations
    │       ↓
    │   Show all user's registrations
    │       ↓
    │   Back to Menu
    │
    ├─→ My Teams
    │       ↓
    │   Show all user's teams
    │       ↓
    │   Back to Menu
    │
    └─→ My Profile
            ↓
        Show user details
            ↓
        Back to Menu

🔑 KEY POINTS TO REMEMBER

1. Registration Happens First

   • When user sends “Hi” for first time
   • Bot checks if phone number exists in database
   • If NO → Starts registration immediately
   • If YES → Shows personalized welcome with name

2. One-by-One Question Flow

   • Bot asks questions sequentially, not all at once
   • User answers one, bot asks next
   • Makes conversation natural
   • Fields: Name → Email (Gmail) → College (list) → Department (list) → Year

3. College & Department from Database

   • Not typed manually (unless “Other”)
   • Bot fetches ALL colleges/departments from database
   • Shows as searchable list (not limited to 10-20)
   • User can search and filter
   • Ensures data consistency

4. Email Must Be Gmail

   • Bot validates @gmail.com format
   • Rejects other email providers
   • Used for notifications and updates

5. Immediate Account Creation

   • After user confirms details, account created immediately
   • No OTP or verification required
   • Yugam ID generated instantly
   • User can start registering for events right away

6. States = Conversation Memory

   • Bot remembers where you are in conversation
   • Changes based on your actions
   • Example: registration_start → collecting_email → registration_complete

7. Payment First, Team Later

   • User pays individually first
   • After payment, bot asks if they want to create team
   • Team creation requires all members to have paid

8. Teams vs Individual

   • Bot detects from event settings (team_size > 1)
   • Team formation happens AFTER payment
   • All team members must have paid individually

9. Payment Flow

   • User registration first (one-time)
   • Event registration second
   • Payment third via Razorpay
   • Confirmation fourth via webhook
   • Team creation fifth (if applicable)

10. General Pass is Special

    • One payment for all general events
    • No individual registrations needed
    • QR code for entry

11. Bot Never Forgets

    • All data saved in database
    • Can resume later
    • Payment reminders automatic

12. Team Creation Rules

    • Payment happens individually first
    • Team creation is optional after payment
    • All team members must have paid before team can be created
    • Can create teams later via “My Teams”
    • Bot takes only required number of IDs (ignores excess)
    • For general events: All members need General Pass
    • For specific events: All members need individual payment

13. Razorpay Integration

    • Secure payment via Razorpay
    • Webhook-based confirmation (instant)
    • Redirects to success/failure pages
    • Payment status tracked in real-time

📱 What Users See vs What Happens Behind

Status: Complete Logic Flow Guide ✅
Last Updated: January 2026
Version: 2.2

Major Updates in v2.2:

• ✅ Instant Registration on First “Hi” Message
• ✅ User existence check when first message received
• ✅ Personalized welcome for existing users (“Hi <Name>!”)
• ✅ Automatic registration flow for new users
• ✅ One-by-one question collection (Name → Email → College → Department → Year)
• ✅ Gmail ID requirement with validation
• ✅ College selection from database list (ALL with search)
• ✅ Department selection from database list (ALL with search)
• ✅ Registration summary with confirm/edit options
• ✅ Immediate account creation (no OTP verification)
• ✅ New bot states for registration flow
• ✅ Updated user journey examples

Major Updates in v2.1:

• ✅ WhatsApp Business Inbox / CRM Dashboard documentation
• ✅ Chat monitoring and management system architecture
• ✅ Real-time conversation tracking
• ✅ Database schema for message storage
• ✅ Agent reply functionality
• ✅ Analytics and user journey tracking

Major Updates in v2.0:

• ✅ Event categories changed to General/Specific/All Events
• ✅ General Event Pass integration with event registration
• ✅ Before-payment forms support
• ✅ Enhanced Razorpay payment flow with webhooks
• ✅ Team creation AFTER payment (not before)
• ✅ Team member payment validation
• ✅ “My Teams” eligibility and team creation
• ✅ Removed combo offers
• ✅ Removed login requirement (WhatsApp bot = authenticated)

Perfect for: Product managers, testers, designers, non-technical stakeholders!