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`)

Your all-in-one solution for collecting information step-by-step — like a guided form that remembers where users left off!

Why Use Wizards?

Perfect for:

📝 Registration Forms — Collect name, email, preferences
🛒 Checkout Flows — Shipping address, payment, confirmation
📋 Surveys — Multi-question questionnaires
⚙️ Onboarding — Walk new users through setup
🎫 Booking Systems — Date, time, guest count

Configuration

Setting	Description
Steps	Array of step configurations (see below)
SaveToVar	Save collected data to this variable
MaxRetries	Global retry limit (can override per-step)
AllowBack	Show "← Previous Step" button

📋 Step Configuration

Each step has these options:

Field	What It Does	Example
id	Unique step name	`"email_step"`
title	Question to ask	`"What's your email?"`
type	Input type (see types below)	`"email"`
required	Must answer to continue?	`true`
validation	Custom rule (expression)	`"len(value) > 5"`
error_message	Show if validation fails	`"Email must be valid"`
show_if	Only show if condition met	`"plan == 'premium'"`
next_step	Jump to specific step	`"payment_step"`
max_retries	Retry limit for this step	`3`
default	Pre-fill value	`"United States"`
options	Choices (for select/confirm)	See examples below

🎨 Input Types

Type	What It Accepts	Example Use
text	Any text	Name, address
number	Numbers only	Age, quantity
email	Valid email format	user@example.com
phone	Phone number	+1-555-0100
url	Web link	https://example.com
select	Multiple choice	Plan selection
confirm	Yes/No	Agree to terms?
photo	User uploads image	Profile picture

Outputs

Output	Description	Type
Complete	All steps finished	Flow
Cancelled	User cancelled wizard	Flow
FormData	All collected answers	Object
CurrentStep	Current step number	Number
TotalSteps	Total step count	Number
ErrorText	Error message if any	String

📚 Complete Examples

Example 1: Simple Registration

{
  "steps": [
    {
      "id": "name",
      "title": "👋 What's your name?",
      "type": "text",
      "required": true
    },
    {
      "id": "email",
      "title": "📧 Enter your email:",
      "type": "email",
      "required": true,
      "error_message": "Please enter a valid email address"
    },
    {
      "id": "age",
      "title": "🎂 How old are you?",
      "type": "number",
      "required": true,
      "validation": "value >= 18",
      "error_message": "You must be 18 or older"
    }
  ],
  "save_to_var": "var.user_registration"
}

Result: When complete, var.user_registration contains:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 25
}

Example 2: Product Order with Branching

{
  "steps": [
    {
      "id": "product",
      "title": "🛍️ What would you like to order?",
      "type": "select",
      "options": [
        { "label": "🖥️ Laptop", "value": "laptop" },
        { "label": "📱 Phone", "value": "phone" },
        { "label": "⌚ Watch", "value": "watch" }
      ]
    },
    {
      "id": "laptop_spec",
      "title": "💻 Choose RAM:",
      "type": "select",
      "show_if": "product == 'laptop'",
      "options": [
        { "label": "8GB - $999", "value": "8gb" },
        { "label": "16GB - $1299", "value": "16gb" }
      ]
    },
    {
      "id": "phone_color",
      "title": "🎨 Choose color:",
      "type": "select",
      "show_if": "product == 'phone'",
      "options": [
        { "label": "Black", "value": "black" },
        { "label": "White", "value": "white" },
        { "label": "Blue", "value": "blue" }
      ]
    },
    {
      "id": "confirm",
      "title": "✅ Confirm your order?",
      "type": "confirm"
    }
  ]
}

How it works:

User selects "Laptop"
Wizard shows laptop_spec (because show_if condition is true)
Wizard SKIPS phone_color (because show_if is false)
Goes to confirm

Example 3: Survey with Smart Branching

{
  "steps": [
    {
      "id": "satisfied",
      "title": "😊 Are you satisfied with our service?",
      "type": "select",
      "options": [
        { "label": "😃 Very Satisfied", "value": "very" },
        { "label": "🙂 Satisfied", "value": "ok" },
        { "label": "😐 Unsatisfied", "value": "bad" }
      ]
    },
    {
      "id": "what_good",
      "title": "💬 What did you like most?",
      "type": "text",
      "show_if": "satisfied == 'very' || satisfied == 'ok'"
    },
    {
      "id": "what_wrong",
      "title": "💔 What went wrong?",
      "type": "text",
      "show_if": "satisfied == 'bad'",
      "required": true
    },
    {
      "id": "recommend",
      "title": "Would you recommend us?",
      "type": "confirm"
    }
  ]
}

Smart flow:

Happy customers → "What did you like?"
Unhappy customers → "What went wrong?"
Everyone → "Would you recommend?"

✨ Advanced Features

🔄 Retry Handling

Set retry limits to prevent frustration:

{
  "id": "password",
  "title": "🔒 Create a strong password:",
  "type": "text",
  "validation": "len(value) >= 8",
  "error_message": "Password must be at least 8 characters",
  "max_retries": 3
}

After 3 failed attempts → Goes to Cancelled output

Jump to different steps based on answers:

{
  "id": "account_type",
  "title": "Choose account type:",
  "type": "select",
  "options": [
    { "label": "Personal", "value": "personal" },
    { "label": "Business", "value": "business" }
  ],
  "next_step": "business_info"  // Skip to business questions
}

💾 Accessing Collected Data

After the wizard completes, access the data:

FormData output → {
  "name": "John",
  "email": "john@example.com",
  "plan": "premium"
}

In templates:

Welcome {{FormData.name}}!
Your plan: {{FormData.plan}}

In variables: If you set save_to_var: "var.signup", then:

{{var.signup.name}}
{{var.signup.email}}

🎯 Best Practices

1. Keep It Short

❌ Don't: 20-step registration ✅ Do: 3-5 essential questions

2. Show Progress

The wizard automatically shows:

Step 2 of 4

3. Use Validation Early

{
  "type": "email",  // ← Validates email format automatically
  "validation": "not includes(value, 'spam')"  // ← Extra custom check
}

4. Smart Branching

Only ask relevant questions:

{
  "show_if": "country == 'USA'",  // ← Only for US users
  "title": "What's your state?"
}

5. Provide Defaults

{
  "id": "country",
  "default": "United States"  // ← Pre-filled
}

🚀 Real-World Use Cases

Hotel Booking

Check-in date
Check-out date
Number of guests
Room type (economy/deluxe/suite)
Breakfast? (yes/no)
Confirm booking

Event Registration

Full name
Email
Company name
Meal preference (vegetarian/non-veg/vegan)
T-shirt size (if attending in-person)
Confirm registration

Support Ticket

Issue category (billing/technical/other)
Describe issue
Upload screenshot (optional)
Priority (low/medium/high)
Submit ticket

📄 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)​

Why Use Wizards?​

Configuration​

📋 Step Configuration​

🎨 Input Types​

Outputs​

📚 Complete Examples​

Example 1: Simple Registration​

Example 2: Product Order with Branching​

Example 3: Survey with Smart Branching​

✨ Advanced Features​

🔄 Retry Handling​

🌳 Dynamic Navigation​

💾 Accessing Collected Data​

🎯 Best Practices​

1. Keep It Short​

2. Show Progress​

3. Use Validation Early​

4. Smart Branching​

5. Provide Defaults​

🚀 Real-World Use Cases​

Hotel Booking​

Event Registration​

Support Ticket​

📄 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`)

Why Use Wizards?

Configuration

📋 Step Configuration

🎨 Input Types

Outputs

📚 Complete Examples

Example 1: Simple Registration

Example 2: Product Order with Branching

Example 3: Survey with Smart Branching

✨ Advanced Features

🔄 Retry Handling

🌳 Dynamic Navigation

💾 Accessing Collected Data

🎯 Best Practices

1. Keep It Short

2. Show Progress

3. Use Validation Early

4. Smart Branching

5. Provide Defaults

🚀 Real-World Use Cases

Hotel Booking

Event Registration

Support Ticket

📄 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