Interactive Menus & Wizards

Build user-friendly navigation systems, multi-step forms, and guided experiences using BotGami's menu nodes.

---

Why Menus?

Benefits:

• ✅ Visual: Buttons instead of text commands
• ✅ Intuitive: Clear options for users
• ✅ State Management: Automatic navigation tracking
• ✅ Mobile-Friendly: Works great on phones

Use Cases:

• Product catalogs with pagination
• Multi-step registration/booking
• Settings panels
• Help systems
• E-commerce checkouts

[Screenshot: Example multi-level menu with categories and products]

---

Menu Basics

Anatomy of a Menu

┌─────────────────────────┐
│ Choose a category:      │ ← Message
│                         │
│ [🍕 Food]  [🎮 Games]  │ ← Buttons (Row 1)
│ [📚 Books] [🏠 Home]    │ ← Buttons (Row 2)
│ [← Back]                 │ ← Navigation
└─────────────────────────┘

menu.show Structure

[menu.show]
  Message: "Choose a category:"
  Items: [
    { label: "🍕 Food", data: "food" },
    { label: "🎮 Games", data: "games" },
    { label: "📚 Books", data: "books" },
    { label: "🏠 Home", data: "home" }
  ]
  Columns: 2  // 2 buttons per row
  AllowBack: true
  
Outputs:
  food → [Show Food Subcategory]
  games → [Show Games]
  books → [Show Books]
  home → [Return to Main]
  Back → [menu.navigate_back]

---

Multi-Level Navigation

Pattern: Main → Category → Item

[Main Menu]
  "What are you looking for?"
  [🛍️ Shop]  [ℹ️ Info]
    ↓ Shop
    
[Category Menu]
  "Choose category:"
  [Electronics] [Clothing] [Books]
  [← Back]
    ↓ Electronics
    
[Electronics List - Paginated]
  Shows 5 items per page
  [Item 1] [Item 2] ...
  [◀️ Prev] [Next ▶️]
  [← Back]
    ↓ Item 1
    
[Item Detail]
  "Product: Laptop Pro
  Price: $999
  Rating: ⭐⭐⭐⭐⭐"
  
  [🛒 Add to Cart] [❤️ Save]
  [← Back to list]

Implementation:

--- Main ---
[menu.show - main_menu]
  Items: [
    { label: "🛍️ Shop", data: "shop" },
    { label: "ℹ️ Info", data: "info" }
  ]
  
  shop → [category_menu]
  
--- Categories ---  
[menu.show - category_menu]
  Items: [
    { label: "💻 Electronics", data: "electronics" },
    { label: "👕 Clothing", data: "clothing" }
  ]
  AllowBack: true
  
  electronics → [electronics_list]
  Back → [menu.navigate_back]  // Goes to main_menu

--- Product List ---
[HTTP GET /api/products?category=electronics]
  ↓ products array
[menu.paginated_list]
  Items: {{products}}
  PageSize: 5
  ItemTemplate: "{{name}} - ${{price}}"
  
  ItemSelected → product_detail

--- Product Detail ---
[data.object_get]
  Object: {{selected_product}}
  ↓ All fields
[menu.show]
  Message: "**{{name}}**
  Price: ${{price}}
  {{description}}"
  
  Items: [
    { label: "🛒 Add to Cart", data: "add_cart" },
    { label: "❤️ Wishlist", data: "wishlist" }
  ]
  AllowBack: true
  
  add_cart → [Add to cart flow]
  Back → [menu.navigate_back]  // Returns to product list

[Screenshot: 4-level navigation showing main→category→list→detail]

---

Wizards (Multi-Step Forms)

menu.wizard

Best for collecting multiple pieces of information in sequence.

Example: User Registration

[menu.wizard - user_registration]
  Steps: [
    {
      name: "full_name",
      message: "👤 What's your full name?",
      type: "text"
    },
    {
      name: "email",
      message: "📧 Enter your email address:",
      type: "text",
      validation: "email"  // Built-in email validation
    },
    {
      name: "age",
      message: "🎂 How old are you?",
      type: "number",
      validation: "value >= 13"
    },
    {
      name: "plan",
      message: "Choose your plan:",
      type: "choice",
      buttons: [
        { label: "Free", data: "free" },
        { label: "Pro - $9/mo", data: "pro" },
        { label: "Enterprise", data: "enterprise" }
      ]
    },
    {
      name: "confirm",
      message: "✅ Review your info:

Name: {{full_name}}
Email: {{email}}
Age: {{age}}
Plan: {{plan}}

Is this correct?",
      type: "choice",
      buttons: [
        { label: "✅ Yes, create account", data: "yes" },
        { label: "❌ Start over", data: "no" }
      ]
    }
  ]
  AllowBack: true
  SaveProgress: true  // Resume if user abandons
  
  Complete → [Process registration]
    Data: {
      full_name: "John Doe",
      email: "john@example.com",
      age: 25,
      plan: "pro",
      confirm: "yes"
    }
    
  Cancel → [Send: "Registration cancelled"]

[Screenshot: Wizard progression showing step 2 of 5]

Validation Types:

• email — Valid email format
• phone — Phone number
• number — Must be numeric
• url — Valid URL
• Custom expression: value >= 18 and value <= 100

---

Pagination

menu.paginated_list

For long lists (products, users, search results).

Example: Product Catalog (100+ items)

[HTTP GET /api/products]
  ↓ 150 products
[menu.paginated_list]
  Items: {{products}}
  PageSize: 8
  ItemTemplate: "{{name}} - ${{price}}"
  Header: "🛍️ Products (Page {{page}}/{{total_pages}})"
  Footer: "Total: {{total_items}} items"
  
Shows:

🛍️ Products (Page 1/19)

Laptop Pro - $999
Mouse Wireless - $25
Keyboard RGB - $75
Monitor 27" - $350
Webcam HD - $120
Headphones - $80
USB Hub - $30
Cable HDMI - $15

Total: 150 items

[◀️ Previous] [Next ▶️]
[🔍 Search] [🏠 Main Menu]

  ItemSelected → [Show product detail]
  Search → [menu.search on same dataset]

[Screenshot: Paginated list showing page 3 of 10]

Pro Tips:

• Keep PageSize between 5-10 for mobile
• Show page numbers in header
• Add search option for long catalogs

---

Dynamic Menus from Data

menu.from_data

Generate menu buttons from API responses or database queries.

Example: User's Saved Items

[db.search_users]
  Filter: user_id == {{user.id}}
  ↓ User
[data.object_get]
  Object: {{User.metadata}}
  Key: "saved_items"
  ↓ saved_items (array of product IDs)
[HTTP POST /api/products/batch]
  Body: { "ids": {{saved_items}} }
  ↓ products array
[menu.from_data]
  DataSource: {{products}}
  LabelTemplate: "{{name}} - ${{price}}"
  DataTemplate: "view_{{id}}"
  Message: "❤️ Your Saved Items:"
  
Generates:
┌────────────────────────────┐
│ ❤️ Your Saved Items:       │
│                            │
│ [Laptop Pro - $999     ]   │
│ [Headphones - $80      ]   │
│ [Mouse - $25           ]   │
└────────────────────────────┘

Each button's callback_data: "view_123", "view_456", etc.

---

Search Menus

menu.search

Let users search through data.

Example: User Directory

[db.search_users]
  Filter: tags contains "active"
  ↓ users array
[menu.search]
  Items: {{users}}
  SearchableFields: ["first_name", "last_name", "username"]
  ResultTemplate: "{{first_name}} (@{{username}})"
  MaxResults: 10
  Placeholder: "Type name to search..."

User types: "john"

Shows:
┌────────────────────────────┐
│ Search results for "john": │
│                            │
│ [John Doe (@johndoe)    ]  │
│ [Johnny Smith (@jsmith) ]  │
│ [John Wilson (@jwilson) ]  │
└────────────────────────────┘

---

Confirmation Dialogs

menu.confirm

Simple yes/no prompts.

Example: Delete Confirmation

User clicks "Delete Account"
  ↓
[menu.confirm]
  Message: "⚠️ **Delete Account?**
  
This will permanently delete all your data.
This action cannot be undone.

Are you absolutely sure?"
  
  YesLabel: "🗑️ Yes, delete everything"
  NoLabel: "❌ No, keep my account"
  
  Yes → [Execute deletion]
  No → [Send: "✅ Account preserved"]

[Screenshot: Confirmation dialog with warning styling]

---

Settings Toggles

menu.toggle

ON/OFF switches for settings.

Example: Notification Settings

[menu.show]
  Message: "⚙️ Settings"
  Items: [
    { label: "🔔 Notifications", data: "notifications" },
    { label: "🌙 Dark Mode", data: "darkmode" }
  ]
  
  notifications →
  
[menu.toggle]
  Variable: "var.notifications_enabled"
  OnLabel: "🔔 Notifications: ON"
  OffLabel: "🔕 Notifications: OFF"
  Message: "Get notified about updates?"
  
Current state shown, user clicks to toggle
Updates var.notifications_enabled automatically

---

Best Practices

1. Button Limits

✅ Max 8 buttons per menu (mobile-friendly)
✅ Use pagination for more
❌ Don't cram 20 buttons

2. Clear Labels

✅ "🛒 View Cart (3 items)"
✅ "💳 Checkout - $45.99"
❌ "opt_a"
❌ "Click here"

3. Always Provide Back

[menu.show]
  AllowBack: true  // ← Always!

Back → [menu.navigate_back]

4. Visual Hierarchy

Use emojis for categories:
🏠 → Home/Main
⚙️ → Settings
ℹ️ → Info/Help
🛒 → Shopping
📊 → Stats/Reports

5. State Management

✅ menu.navigate_back - automatic breadcrumbs
✅ menu.reset - return to main after flows
❌ Manual state tracking - error-prone

---

Common Patterns

Pattern 1: Settings Panel

Main → Settings → Subsection → Toggle/Edit → Back → Back → Main

Pattern 2: E-Commerce

Main → Categories → Products (paginated) → Product Detail → Add to Cart → Checkout
                                          ↑                              │
                                          └──────────────────────────────┘
                                                    (Back navigation)

Pattern 3: Help System

Main → Help Topics → Topic Articles (search) → Article Detail → Was this helpful? (confirm)

Pattern 4: Onboarding Wizard

Welcome → [wizard: steps 1-5] → Complete setup → Main Menu

---

Complete Example: Pizza Ordering Bot

--- Start ---
[/start command]
  ↓
[menu.show - main]
  "🍕 Welcome to Pizza Bot!"
  [🛒 Order Now] [📜 My Orders] [ℹ️ About]
  
  Order Now →

--- Pizza Selection ---  
[menu.from_data]
  DataSource: [
    { id: 1, name: "Margherita", price: 12 },
    { id: 2, name: "Pepperoni", price: 14 },
    { id: 3, name: "Hawaiian", price: 13 }
  ]
  LabelTemplate: "{{name}} - ${{price}}"
  Message: "Choose your pizza:"
  
  pizza_1 →
  
--- Size Selection ---
[menu.show]
  Message: "Margherita selected. Choose size:"
  Items: [
    { label: "Small - $12", data: "small" },
    { label: "Medium - $15", data: "medium" },
    { label: "Large - $18", data: "large" }
  ]
  AllowBack: true
  
  medium → [Save selection]

--- Confirmation ---  
[menu.confirm]
  Message: "**Order Summary:**

Pizza: Margherita (Medium)
Price: $15.00

Confirm order?"
  
  YesLabel: "✅ Place Order"
  NoLabel: "❌ Cancel"
  
  Yes → 
  
--- Payment ---
[menu.show]
  "💳 Payment Method:"
  [Credit Card] [PayPal] [Cash on Delivery]
  
  → Process payment → Success!
  
[menu.reset - Return to main menu]

---

Troubleshooting

Issue: Clicking Back goes to wrong menu
Fix: Use menu.navigate_back - tracks history automatically

Issue: Menu buttons not appearing
Check: Items array format, label field exists

Issue: Can't return to main after wizard
Fix: Use menu.reset after completion

---

Quick Reference

Node	Use For
menu.show	Basic choice menus
menu.wizard	Multi-step forms (3+ steps)
menu.paginated_list	Long lists (10+ items)
menu.from_data	Dynamic menus from APIs
menu.search	Searchable directories
menu.confirm	Yes/No dialogs
menu.toggle	Settings switches
menu.navigate_back	Back button behavior
menu.reset	Return to specific menu

---

Next Steps

• Menu Nodes Reference → — Complete node docs
• Flow Control → — Questions and forms