Copy page

Basics

Navigation & Terminal Menus

Navigation & Terminal Menus

This guide covers navigation patterns in USSD applications, including global navigation actions, back/home keys, terminal menus, and navigation history management.

Navigation Overview

USSD applications navigate between menus based on user input. The platform supports several navigation patterns:

Pattern	Description
Option selection	User selects a numbered option to navigate
Wildcard input	User enters free-form text matched by "*" option
Global actions	Consistent Back/Home keys across all menus
Terminal menus	End session after displaying content
Data-driven pagination	Navigate pages in data-driven menus

Global Navigation Actions

Configure consistent Back and Home keys that work from any menu using the global_actions block.

Configuration

Code
app "BankingApp" {
  shortcode = "*123#"
  version   = "2.0.0"
  start     = "MainMenu"

  options {
    global_actions {
      back_key = "0"    # Press 0 to go back
      home_key = "99"   # Press 99 to return to start
    }
  }
}

Properties

Property	Type	Description
back_key	string	Key that returns to previous menu in history
home_key	string	Key that returns to application's start menu

Behavior

• Back key: Navigates to the previous menu in the navigation history stack
• Home key: Navigates directly to the start menu, clearing history
• Global actions are checked before menu-specific options
• When at the start menu, the back key has no effect (nowhere to go)

Example

Code
app "MyApp" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "MainMenu"

  options {
    global_actions {
      back_key = "0"
      home_key = "99"
    }
  }
}

menu "MainMenu" {
  text = "Main Menu"

  option "1" {
    label = "Services"
    goto  = "ServicesMenu"
  }

  option "2" {
    label = "Settings"
    goto  = "SettingsMenu"
  }
}

menu "ServicesMenu" {
  text = "Services"

  option "1" {
    label = "Balance"
    goto  = "BalanceMenu"
  }

  option "2" {
    label = "Transfer"
    goto  = "TransferMenu"
  }
  # No explicit "Back" option needed - user presses 0
}

menu "BalanceMenu" {
  text = "Your balance: $100.00"
  # User can press 0 to go back to ServicesMenu
  # User can press 99 to go back to MainMenu
}

Navigation History

The platform maintains a navigation history stack for each session. This enables proper Back navigation through multiple menu levels.

How History Works

1. When navigating from Menu A to Menu B, Menu A is pushed onto the history stack
2. When user presses the back key, the platform pops Menu A and navigates to it
3. Home navigation clears the entire history stack

Example Flow

Code
User dials *123# → MainMenu
  → Presses 1 → ServicesMenu (history: [MainMenu])
    → Presses 1 → BalanceMenu (history: [MainMenu, ServicesMenu])
      → Presses 0 (back) → ServicesMenu (history: [MainMenu])
        → Presses 99 (home) → MainMenu (history: [])

Terminal Menus

Terminal menus end the USSD session after displaying content. They're used for confirmations, results, and goodbye messages.

Implicit Terminal (No Options)

A menu with no options automatically ends the session:

Code
menu "Goodbye" {
  text = "Thank you for using our service. Goodbye!"
  # No options = session ends after displaying this message
}

Explicit Terminal Flag

Use terminal = true to end the session even when options are defined:

Code
menu "TransferSuccess" {
  text = "Transfer successful!\n\nAmount: ${{session.data.amount}}\nRecipient: {{session.data.recipient}}"
  terminal = true  # Session ends regardless of any defined options
}

When to Use Terminal Menus

Use Case	Recommendation
Success confirmation	terminal = true
Error with no retry	terminal = true
Goodbye message	Empty options (implicit)
Search results	Empty options (implicit)
Session timeout	terminal = true

Example: Terminal Results

Code
menu "SearchInput" {
  text = "Enter phone number to search:"

  option "*" {
    label = "Search"
    goto  = "SearchAction"
  }
}

action "SearchAction" {
  type       = "http_call"
  url        = "/api/users/search?phone={{session.input}}"
  on_success = "SearchResult"
  on_error   = "SearchError"
}

menu "SearchResult" {
  text = "Found: {{response.name}}\nStatus: {{response.status}}"
  # No options = terminal, session ends
}

menu "SearchError" {
  text = "User not found or search failed."
  terminal = true  # Explicit terminal for error
}

Back Navigation Without Global Actions

If you don't use global_actions, define explicit Back options in each menu:

Code
menu "MainMenu" {
  text = "Main Menu"

  option "1" {
    label = "Services"
    goto  = "ServicesMenu"
  }
}

menu "ServicesMenu" {
  text = "Services"

  option "1" {
    label = "Balance"
    goto  = "BalanceMenu"
  }

  option "0" {
    label = "Back"
    goto  = "MainMenu"  # Explicit back navigation
  }
}

menu "BalanceMenu" {
  text = "Your balance: $100.00"

  option "0" {
    label = "Back"
    goto  = "ServicesMenu"  # Each menu defines its own back target
  }
}

Data-Driven Menu Navigation

Data-driven menus have built-in pagination using reserved keys:

Key	Action
1-N	Select item N from current page
8	Previous page
9	Next page

Code
menu "ProductList" {
  text = "Products:"

  data_source {
    url              = "/products"
    display_template = "{{name}} - ${{price}}"
    on_select        = "ProductDetail"
    page_size        = 5
    next_label       = "More"      # Shown as "9. More"
    previous_label   = "Back"      # Shown as "8. Back"
  }
}

Rendered Output (Page 1 of 3)

Code
Products:
1. Phone - $299
2. Tablet - $499
3. Laptop - $899
4. Watch - $199
5. Earbuds - $79
9. More
0. Back

Combining Patterns

You can combine global actions with data-driven menus:

Code
app "StoreApp" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "MainMenu"

  options {
    global_actions {
      back_key = "0"
      home_key = "99"
    }
  }
}

menu "MainMenu" {
  text = "Welcome to Store"

  option "1" {
    label = "Browse Products"
    goto  = "ProductList"
  }
}

menu "ProductList" {
  text = "Products:"

  data_source {
    url              = "/products"
    display_template = "{{name}}"
    on_select        = "ProductDetail"
    page_size        = 5
  }
  # Keys 1-5: Select item
  # Key 8: Previous page
  # Key 9: Next page
  # Key 0: Global back
  # Key 99: Global home
}

Best Practices

1. Use global_actions for consistency — Configure Back/Home once instead of in every menu.

2. Don't duplicate Back options — If using global_actions, omit explicit Back options to avoid confusion.

3. Terminal menus for final states — Use terminal menus for success/error messages where no further action is needed.

4. Test navigation paths — Verify Back navigation works through multiple levels.

5. Consider Home for deep menus — For apps with many levels, provide a Home key for quick restart.

6. Document navigation — Include navigation instructions in menu text when needed:

Code
menu "DeepMenu" {
  text = "Some content...\n\n(Press 0 to go back, 99 for main menu)"
}