Menu Nodes

Build interactive menus, wizards, and navigation systems. These nodes handle user choices, pagination, multi-step forms, and complex menu hierarchies.

Menu nodes provide a structured way to build interactive experiences:

✅ User-Friendly: Visual buttons instead of text commands
✅ State Management: Auto-tracks menu navigation
✅ Built-in Navigation: Back buttons, breadcrumbs
✅ Pagination: Handle large lists elegantly

Example of multi-level menu with back navigation

📋 Show Menu (`menu.show`)

The core menu node that displays options and handles user selection.

Configuration

Setting	Description
Message	Text to show above buttons
Items	Array of menu options
Columns	Buttons per row (1-3)
AllowBack	Show "← Back" button
ParseMode	Markdown/HTML formatting

Item Format

Each menu item is an object:

{
  "label": "📦 View Products",
  "data": "show_products",
  "url": "https://shop.com" // Optional link
}

Dynamic Outputs

The node creates output sockets for each menu item:

One output per item (based on data field)
Back output (if enabled)
Cancel output (optional)

menu.show:
  Message: "Welcome! What would you like to do?"
  Items: [
    { label: "🛍️ Browse Products", data: "products" },
    { label: "📞 Contact Support", data: "support" },
    { label: "ℹ️ About Us", data: "about" }
  ]
  Columns: 2

Outputs:
  products → [Show ProductsCatalog]
  support → [Start Support Chat]
  about → [Send About Info]

[Screenshot: menu.show node showing 3 items and their corresponding output sockets]

🧙 Multi-Step Wizard (`menu.wizard`)

Guide users through a multi-step process with automatic state tracking.

Configuration

Setting	Description
Steps	Array of step configurations
AllowBack	Enable "← Previous" button
SaveProgress	Remember incomplete wizards

Step Format

{
  "name": "step_name",
  "message": "Enter your email:",
  "validation": "email", // Optional: email, phone, number
  "buttons": [ ... ] // Optional choice buttons
}

Outputs

Output	Description
`Complete`	All steps finished
`Cancel`	User canceled
`Data`	Collected data (object)

Example: Registration Wizard

menu.wizard:
  Steps: [
    {
      name: "name",
      message: "👋 What's your name?"
    },
    {
      name: "email",
      message: "📧 Enter your email:",
      validation: "email"
    },
    {
      name: "plan",
      message: "Choose your plan:",
      buttons: [
        { label: "Free", data: "free" },
        { label: "Pro - $9/mo", data: "pro" }
      ]
    }
  ]

Complete output → Data: {
  name: "John Doe",
  email: "john@example.com",
  plan: "pro"
}

[Screenshot: Wizard stepping through name → email → plan selection]

Use Cases:

User registration/onboarding
Multi-step forms (booking, checkout)
Surveys and questionnaires
Settings configuration

📄 Paginated List (`menu.paginated_list`)

Display large lists with navigation buttons (Next/Previous).

Configuration

Setting	Description
Items	Array of all items
PageSize	Items per page (default: 5)
ItemTemplate	How to format each item
Header	Message above list

Outputs

Output	Description
`ItemSelected`	User clicked an item
`SelectedItem`	The selected item data
`SelectedIndex`	Item's array index

Example: Product Catalog

menu.paginated_list:
  Items: [
    { name: "Laptop", price: 999 },
    { name: "Mouse", price: 25 },
    { name: "Keyboard", price: 75 },
    ... 50 more products
  ]
  PageSize: 5
  ItemTemplate: "{{name}} - ${{price}}"
  Header: "🛍️ Our Products (Page {{page}}/{{total_pages}})"

Shows:
Page 1/10
🛍️ Our Products

Laptop - $999
Mouse - $25
Keyboard - $75
Monitor - $350
Webcam - $120

[◀️ Previous] [Next ▶️]

[Screenshot: Paginated list showing Page 2 of 5 with navigation buttons]

Use Cases:

Product catalogs
Search results
User lists
Content browse

🔀 Menu Router (`menu.router`)

Route to different submenus based on user selection, creating hierarchical navigation.

Configuration

Setting	Description
Routes	Map of data → submenu
DefaultRoute	Fallback menu

Main Menu
  ↓
[menu.router]
  products → Product Categories Menu
  support → Support Options Menu
  settings → Settings Menu

Use Case: Complex navigation trees (e-commerce, help centers)

⬅️ Navigate Back (`menu.navigate_back`)

Return to the previous menu in the navigation stack.

Configuration

Setting	Description
Message	Optional text when going back

How It Works

BotGami automatically tracks menu navigation history. This node pops the stack:

User flow:
Main → Products → Category → Item
                    ↑
            [Navigate Back]
Goes back to: Category

Every menu.show has AllowBack: true
  ↓
Each "Back" output connects to menu.navigate_back
  ↓
Automatic breadcrumb trail

[Screenshot: Menu showing "← Back" button with breadcrumb path]

🔄 Reset Menu (`menu.reset`)

Clear navigation history and return to a specific menu (usually main).

Configuration

Setting	Description
TargetMenu	Menu ID to reset to
Message	Optional reset message

Example: Return to Main

User finishes checkout
  ↓
[menu.reset → main_menu]
  ↓
"✅ Order complete! Returning to main menu..."

Use Cases:

After completing a workflow
Timeout/idle cleanup
Error recovery

❓ Confirmation Dialog (`menu.confirm`)

Simple Yes/No confirmation prompt.

Configuration

Setting	Description
Message	Question to ask
YesLabel	Custom "Yes" button text
NoLabel	Custom "No" button text

Outputs

Output	Description
`Yes`	User confirmed
`No`	User declined

Example: Delete Confirmation

menu.confirm:
  Message: "🗑️ Delete this item? This cannot be undone."
  YesLabel: "✅ Yes, delete it"
  NoLabel: "❌ No, keep it"

  Yes → [Execute deletion]
  No → [Cancel action]

[Screenshot: Confirmation dialog with styled Yes/No buttons]

🔍 Search Menu (`menu.search`)

Let users search through a list and select results.

Configuration

Setting	Description
SearchableFields	Which fields to search
Items	Data source array
ResultTemplate	How to display results
MaxResults	Limit displayed results

Example: User Search

menu.search:
  Items: [ ...array of users ]
  SearchableFields: ["name", "email"]
  ResultTemplate: "{{name}} ({{email}})"
  MaxResults: 10

User types: "john"
  ↓
Shows: John Doe (john@example.com)
       John Smith (jsmith@example.com)

Use Cases:

User directory
Product search
Content discovery

Toggle Switch (`menu.toggle`)

ON/OFF switch for settings.

Configuration

Setting	Description
Variable	Which var to toggle
OnLabel	Text when ON
OffLabel	Text when OFF

Example: Notifications Setting

menu.toggle:
  Variable: "var.notifications_enabled"
  OnLabel: "🔔 Notifications ON"
  OffLabel: "🔕 Notifications OFF"

Current state shown with appropriate icon/label
User clicks → Value toggles

📝 Dynamic Menu from Data (`menu.from_data`)

Generate menu items dynamically from an array or API response.

Configuration

Setting	Description
DataSource	Array or object to generate from
LabelTemplate	How to format button labels
DataTemplate	What to put in callback data

[HTTP GET /api/categories]
  ↓ Response: [
    { id: 1, name: "Electronics" },
    { id: 2, name: "Clothing" },
    { id: 3, name: "Books" }
  ]
  ↓
[menu.from_data]
  DataSource: (connected to HTTP response)
  LabelTemplate: "{{name}}"
  DataTemplate: "cat_{{id}}"
  ↓
Generates menu:
  🏷️ Electronics (callback: cat_1)
  🏷️ Clothing (callback: cat_2)
  🏷️ Books (callback: cat_3)

[Screenshot: Dynamic menu generated from API data]

Use Cases:

Database-driven menus
Dynamic catalogs
User-generated content lists

Best Practices

1. Keep Menus Simple

Max 6-8 buttons per menu
Use pagination for more
Clear, concise labels

2. Always Provide "Back"

menu.show:
  AllowBack: true

Each menu connects its Back output to menu.navigate_back

3. Use Wizards for Multi-Step

Don't build complex flows manually — use menu.wizard:

❌ manual.question → question → question → ...
✅ menu.wizard (automatic state, navigation, validation)

4. Icons in Labels

Makes menus more visual:

Items: [
  { label: "🛍️ Shop", data: "shop" },
  { label: "📦 Orders", data: "orders" },
  { label: "⚙️ Settings", data: "settings" }
]

[menu.show]
  ↓ (after 5 minutes)
[menu.reset]
  Message: "Session expired. Returning to main menu."

Common Patterns

[Main Menu]
   ├─ products → [Product Categories Menu]
   │               ├─ electronics → [Electronics List]
   │               └─ clothing → [Clothing List]
   ├─ support → [Support Menu]
   └─ settings → [Settings Menu]

Pattern 2: List → Detail → Action

[Paginated Product List]
  → Select Item
  → [Product Detail Menu]
      ├─ Add to Cart
      ├─ View Specs
      └─ ← Back to List

Pattern 3: Wizard → Confirmation → Result

[Registration Wizard]
  → Collect: name, email, plan
  → [Confirmation: "Create account with these details?"]
      ├─ Yes → [Create Account] → [Success Menu]
      └─ No → [Back to Wizard]

Quick Reference

Node	Use For
`menu.show`	Basic choice menus
`menu.wizard`	Multi-step forms
`menu.paginated_list`	Long lists (products, search)
`menu.router`	Hierarchical navigation
`menu.navigate_back`	Back button behavior
`menu.reset`	Return to main/start
`menu.confirm`	Yes/No dialogs
`menu.search`	Searchable lists
`menu.toggle`	ON/OFF settings
`menu.from_data`	Dynamic menus from data

Next Steps

Creating a Wizard Tutorial → — Step-by-step wizard example
Advanced Topics: Menus → — Deep dive into menu patterns
Flow Control → — Control conversation flow

Why Use Menu Nodes?​

📋 Show Menu (menu.show)​

Configuration​

Item Format​

Dynamic Outputs​

Example: Main Menu​

🧙 Multi-Step Wizard (menu.wizard)​

Configuration​

Step Format​

Outputs​

Example: Registration Wizard​

📄 Paginated List (menu.paginated_list)​

Configuration​

Outputs​

Example: Product Catalog​

🔀 Menu Router (menu.router)​

Configuration​

Example: Multi-level Navigation​

⬅️ Navigate Back (menu.navigate_back)​

Configuration​

How It Works​

Example: Breadcrumb Navigation​

🔄 Reset Menu (menu.reset)​

Configuration​

Example: Return to Main​

❓ Confirmation Dialog (menu.confirm)​

Configuration​

Outputs​

Example: Delete Confirmation​

🔍 Search Menu (menu.search)​

Configuration​

Example: User Search​

Toggle Switch (menu.toggle)​

Configuration​

Example: Notifications Setting​

📝 Dynamic Menu from Data (menu.from_data)​

Configuration​

Example: Category Menu from Database​

Best Practices​

1. Keep Menus Simple​

2. Always Provide "Back"​

3. Use Wizards for Multi-Step​

4. Icons in Labels​

5. Handle Menu Timeout​

Common Patterns​

Pattern 1: Main Menu → Submenus​

Pattern 2: List → Detail → Action​

Pattern 3: Wizard → Confirmation → Result​

Quick Reference​

Next Steps​

Why Use Menu Nodes?

📋 Show Menu (`menu.show`)

Configuration

Item Format

Dynamic Outputs

Example: Main Menu

🧙 Multi-Step Wizard (`menu.wizard`)

Configuration

Step Format

Outputs

Example: Registration Wizard

📄 Paginated List (`menu.paginated_list`)

Configuration

Outputs

Example: Product Catalog

🔀 Menu Router (`menu.router`)

Configuration

Example: Multi-level Navigation

⬅️ Navigate Back (`menu.navigate_back`)

Configuration

How It Works

Example: Breadcrumb Navigation

🔄 Reset Menu (`menu.reset`)

Configuration

Example: Return to Main

❓ Confirmation Dialog (`menu.confirm`)

Configuration

Outputs

Example: Delete Confirmation

🔍 Search Menu (`menu.search`)

Configuration

Example: User Search

Toggle Switch (`menu.toggle`)

Configuration

Example: Notifications Setting

📝 Dynamic Menu from Data (`menu.from_data`)

Configuration

Example: Category Menu from Database

Best Practices

1. Keep Menus Simple

2. Always Provide "Back"

3. Use Wizards for Multi-Step

4. Icons in Labels

5. Handle Menu Timeout

Common Patterns

Pattern 1: Main Menu → Submenus

Pattern 2: List → Detail → Action

Pattern 3: Wizard → Confirmation → Result

Quick Reference

Next Steps