Build & Test

USSD Application DSL Guide

Build interactive USSD applications using our simple, declarative domain-specific language (DSL). Define menus, actions, and navigation flows without writing code.

Quick Start

Here's a complete example of a simple banking USSD application:

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

menu "MainMenu" {
  text = "Welcome to MyBank! Select an option:"
  
  option "1" {
    label = "Check Balance"
    goto  = "CheckBalance"
  }
  
  option "2" {
    label = "Transfer Money"
    goto  = "TransferMenu"
  }
  
  option "3" {
    label = "Buy Airtime"
    goto  = "AirtimeMenu"
  }
}

menu "CheckBalance" {
  text = "Your balance is: $500.00"
  
  option "0" {
    label = "Main Menu"
    goto  = "MainMenu"
  }
}

menu "TransferMenu" {
  text = "Enter recipient phone number:"
  
  option "0" {
    label = "Cancel"
    goto  = "MainMenu"
  }
}

menu "AirtimeMenu" {
  text = "Select airtime amount:"
  
  option "1" {
    label = "$5"
    goto  = "ConfirmAirtime"
  }
  
  option "2" {
    label = "$10"
    goto  = "ConfirmAirtime"
  }
  
  option "0" {
    label = "Back"
    goto  = "MainMenu"
  }
}

menu "ConfirmAirtime" {
  text = "Airtime purchased successfully!\n\nPress 0 to return."
  
  option "0" {
    label = "Main Menu"
    goto  = "MainMenu"
  }
}

DSL Syntax

Application Block

Every USSD application starts with an app block that defines metadata:

Code
app "ApplicationName" {
  shortcode = "*123#"    # USSD short code
  version   = "1.0.0"    # Semantic version
  start     = "MainMenu" # First screen to show
}

Property	Required	Description
`shortcode`	Yes	The USSD code users dial (e.g., `123#`, `555*1#`)
`version`	Yes	Semantic version for tracking changes
`start`	Yes	Name of the first menu to display

Menus display text and options to users:

Code
menu "MenuName" {
  text = "Display this text to the user"
  
  option "1" {
    label = "Option description"
    goto  = "NextMenu"
  }
  
  option "2" {
    label = "Another option"
    goto  = "AnotherMenu"
  }
}

Property	Required	Description
`text`	Yes	Message displayed to the user
`option`	No	Navigation options (can have multiple)

Option Properties

Property	Required	Description
`label`	Yes	Description shown to user
`goto`	Yes	Target menu or action name

Action Blocks

Actions perform operations like API calls:

Code
action "Finance.CheckBalance" {
  type = "http_call"
  
  url     = "https://api.mybank.com/balance"
  method  = "GET"
  timeout = 30
  
  on_success = "BalanceResult"
  on_error   = "ErrorMenu"
}

Property	Required	Description
`type`	Yes	Action type (currently `http_call`)
`url`	Yes	API endpoint URL
`method`	No	HTTP method (default: `GET`)
`timeout`	No	Timeout in seconds (default: `30`)
`on_success`	Yes	Menu to show on success
`on_error`	Yes	Menu to show on error

Application Configuration

New in v2.0 — Configure global settings for HTTP calls, environment variables, and authentication.

Applications can define global configuration that applies to all actions:

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

  options {
    http_base_url = "https://api.mybank.com/v1"
    secrets_engine = {
      provider = "tenant_vault"
      path     = "tenants/{{org.id}}/apps/{{app.name}}"
    }
  }

  env = {
    API_KEY     = "{{secrets.api_key}}"
    ENVIRONMENT = "production"
    TIMEOUT     = "30"
  }

  auth {
    type     = "api_key"
    header   = "X-API-Key"
    value    = "{{env.API_KEY}}"
  }

  menu "MainMenu" { ... }
}

Options Block

Configure global HTTP and secrets settings:

Property	Required	Description
`http_base_url`	No	Base URL for relative `http_call` URLs
`secrets_engine`	No	Tenant-scoped secrets provider configuration

When http_base_url is set, actions can use relative URLs:

Code
# With http_base_url = "https://api.mybank.com/v1"
action "GetBalance" {
  type = "http_call"
  url  = "/accounts/balance"  # Resolves to https://api.mybank.com/v1/accounts/balance
}

Environment Variables (env)

Define environment variables accessible via {{env.*}} templates:

Code
env = {
  API_KEY     = "{{secrets.api_key}}"
  RETRY_COUNT = "3"
  DEBUG_MODE  = "false"
}

Use in actions:

Code
action "CallAPI" {
  type    = "http_call"
  url     = "{{options.http_base_url}}/data"
  timeout = "{{env.RETRY_COUNT}}"
}

Authentication (auth)

Configure global authentication applied to all HTTP calls:

Basic Authentication:

Code
auth {
  type     = "basic"
  username = "api_user"
  password = "{{secrets.api_password}}"
}

API Key Authentication:

Code
auth {
  type        = "api_key"
  header      = "X-API-Key"        # Use header-based auth
  # query_param = "api_key"        # Or use query parameter
  value       = "{{env.API_KEY}}"
}

OAuth2 Client Credentials:

Code
auth {
  type          = "oauth2_client_credentials"
  token_url     = "https://auth.mybank.com/oauth/token"
  client_id     = "{{secrets.client_id}}"
  client_secret = "{{secrets.client_secret}}"
  scope         = "read:accounts write:transfers"
}

Per-Action Auth Override

Override or disable authentication for specific actions:

Code
# Override with different auth
action "PublicEndpoint" {
  type = "http_call"
  url  = "/public/status"
  auth = "none"  # Disable auth for this action
}

action "AdminEndpoint" {
  type = "http_call"
  url  = "/admin/config"
  auth {
    type     = "basic"
    username = "admin"
    password = "{{secrets.admin_password}}"
  }
}

New in v2.1 — Configure consistent Back and Home keys across all menus.

The global_actions block enables navigation shortcuts that work from any menu:

Code
options {
  http_base_url = "https://api.mybank.com/v1"
  
  global_actions {
    back_key = "0"    # Press 0 to go back anywhere
    home_key = "99"   # Press 99 to return to start menu
  }
}

Property	Required	Description
`back_key`	No	Key that returns to the previous menu in navigation history
`home_key`	No	Key that returns to the application's `start` menu

Global actions are checked before menu-specific options, ensuring consistent behavior across all menus. See Navigation & Terminal Menus for detailed examples.

Comments

Add comments using # or //:

Code
# This is a comment
// This is also a comment

app "MyApp" {
  shortcode = "*123#"  # Inline comment
  version   = "1.0.0"
  start     = "Main"
}

Action Chains and Actions

Action execution now happens through action chains attached to menu options or transitions. An action chain is an ordered list of inline actions, with optional error routing and transactional rollback.

Code
menu "TransferMenu" {
  text = "Enter amount to transfer:"

  option "*" {
    label = "Any amount"
    goto  = "ConfirmTransfer"
    actions = [
      {
        name   = "normalize-amount"
        type   = "string"
        op     = "trim"
        inputs = ["{{session.input}}"]
        target = "amount"
      },
      {
        name   = "amount-range"
        type   = "validate"
        source = "amount"
        min    = 1
        max    = 10000
      }
    ]
    error_target = "InvalidAmount"
    transactional = true
  }
}

For full details on action chains, inline action fields, and error handling, see:

Legacy Action Blocks (Compatibility)

Legacy action blocks are still parsed for backward compatibility, but new work should prefer inline action chains.

Code
action "Account.GetBalance" {
  type = "http_call"
  url  = "https://api.example.com/balance"
  on_success = "BalanceResult"
  on_error   = "ErrorScreen"
}

Template Variables

Updated: January 2025 - Added env.*, options.*, and secrets.* variables

Use double curly braces {{...}} to insert dynamic values:

Variable	Description	Example
`{{session.msisdn}}`	User's phone number	`+231886123456`
`{{session.id}}`	Current session ID	`sess_abc123`
`{{session.shortcode}}`	USSD shortcode dialed	`*123#`
`{{session.input}}`	User's last input	`1`
`{{session.networkid}}`	Mobile network identifier	`orange-lr`
`{{session.data.*}}`	Stored session data	`{{session.data.amount}}`
`{{response.*}}`	API response fields	`{{response.balance}}`
`{{response.nested.path}}`	Nested API response data	`{{response.user.name}}`
`{{config.*}}`	Application config	`{{config.api_key}}`
`{{env.*}}`	Environment variables from `env` block	`{{env.API_KEY}}`
`{{options.http_base_url}}`	Global HTTP base URL	`https://api.example.com`
`{{secrets.*}}`	Tenant-scoped secrets (requires `secrets_engine`)	`{{secrets.api_key}}`
`{{org.id}}`	Current tenant/organization ID	`org_abc123`
`{{app.name}}`	Application name	`MyBankingApp`

Best Practices

1. Always Provide a Back Option

Code
menu "SubMenu" {
  text = "Select an option:"
  
  option "1" {
    label = "Do something"
    goto  = "Action"
  }
  
  option "0" {
    label = "Back"      # Always include a way back
    goto  = "MainMenu"
  }
}

2. Use Descriptive Names

Code
# Good - clear and descriptive
menu "AccountBalanceResult" { ... }
action "Finance.TransferFunds" { ... }

# Avoid - unclear
menu "Menu1" { ... }
action "Action2" { ... }

3. Organize Actions with Dot Notation

Group related actions using dot notation:

Code
action "Finance.CheckBalance" { ... }
action "Finance.TransferFunds" { ... }
action "Finance.ViewHistory" { ... }

action "Airtime.Purchase" { ... }
action "Airtime.CheckBundle" { ... }

USSD screens have character limits (typically 160-182 characters). Keep messages short:

Code
# Good - concise
menu "Balance" {
  text = "Balance: $500.00"
  
  option "0" {
    label = "Back"
    goto  = "MainMenu"
  }
}

# Avoid - too long
menu "Balance" {
  text = "Your current account balance as of today is five hundred dollars and zero cents. Please press 0 to return to the main menu or press 1 to view transaction history."
}

5. Version Your Applications

Use semantic versioning to track changes:

Code
app "MyApp" {
  version = "1.0.0"  # Initial release
  # version = "1.1.0"  # New feature added
  # version = "2.0.0"  # Breaking changes
}

New in v2.1 — Enhanced navigation controls with Back/Home actions and terminal menus.

Menus can reference their parent menus to enable Back navigation. Unlike action-only cycles, menu-to-menu references are safe because they require explicit user input to traverse.

Code
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"
  }
  
  option "0" {
    label = "Back"
    goto  = "MainMenu"    # Safe: Requires user input to navigate back
  }
}

menu "BalanceMenu" {
  text = "Your balance: $100.00"
  
  option "0" {
    label = "Back"
    goto  = "ServicesMenu"  # Safe: Multi-level back navigation
  }
}

Configure consistent Back and Home keys across all menus using the global_actions block in your app options:

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

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

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"
  }
}

menu "BalanceMenu" {
  text = "Your balance: $100.00"
  # No explicit Back option needed - user presses 0 globally
}

With global_actions configured:

Back key (0): Returns to the previous menu in navigation history
Home key (99): Returns to the application's start menu

Global actions are checked before menu-specific options, so they work consistently across all menus. When the user is already at the start menu, the Back key has no effect (nowhere to go back to).

Terminal Menus

Terminal menus end the USSD session after displaying content. There are two ways to create terminal menus:

1. Empty Options (Implicit Terminal)

A menu with no options automatically ends the session:

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

2. Explicit Terminal Flag

Use terminal = true for menus that should end the session even if they have options defined for other purposes:

Code
menu "TransferComplete" {
  text = "Transfer successful!\nAmount: ${{session.data.amount}}\nRecipient: {{session.data.recipient}}"
  terminal = true  # Session ends after displaying this message
}

Property	Type	Default	Description
`terminal`	boolean	`false`	When `true`, the menu ends the session regardless of defined options

Terminal Search Results

Search result menus commonly use the terminal pattern to display results and end the session:

Code
menu "SearchInput" {
  text = "Enter phone number to search:"
  
  option "*" {
    label = "Search"
    goto  = "PerformSearch"
  }
}

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

menu "SearchResult" {
  text = "Search Result:\nName: {{response.name}}\nStatus: {{response.status}}"
  # No options = terminal, session ends after showing result
}

menu "SearchError" {
  text = "Search failed. Please try again later."
  terminal = true  # Explicit terminal for error state
}

Use global_actions for consistency: Configure Back/Home keys once instead of repeating in every menu.
Don't mix global and explicit Back options: If using global_actions, omit explicit Back options to avoid confusion or conflicts.
Terminal menus for confirmations: Use terminal menus for success/error messages where no further action is needed.
Test deep navigation: Ensure Back navigation works correctly through multiple menu levels.
Consider Home for deep menus: For apps with many levels, provide a Home key so users can quickly restart.

Open-Ended User Input

Tip: Use wildcard options to capture free-form user input like names, amounts, or phone numbers.

Wildcard Options

The wildcard selector (*) matches any input that doesn't match a specific option:

Code
menu "EnterPhone" {
  text = "Enter phone number:"
  
  option "*" {
    label = "Any input"
    goto  = "ConfirmPhone"
  }
}

menu "ConfirmPhone" {
  text = "You entered: {{session.input}}"
  
  option "1" {
    label = "Confirm"
    goto  = "ProcessPhone"
  }
  
  option "2" {
    label = "Re-enter"
    goto  = "EnterPhone"
  }
}

The user's input is automatically available via {{session.input}} in the next menu or action.

Combining Wildcards with Specific Options

You can mix wildcard with specific options. Specific options are matched first:

Code
menu "AmountEntry" {
  text = "Enter amount or select:"
  
  option "1" {
    label = "$10"
    goto  = "ConfirmTransfer"
  }
  
  option "2" {
    label = "$20"
    goto  = "ConfirmTransfer"
  }
  
  option "3" {
    label = "$50"
    goto  = "ConfirmTransfer"
  }
  
  option "*" {
    label = "Custom amount"
    goto  = "ValidateAmount"
  }
}

When user enters "1", "2", or "3", the specific option is matched. Any other input (like "75" or "100") triggers the wildcard.

Using Input in API Calls

Pass captured input to backend APIs:

Code
menu "SearchUser" {
  text = "Enter user ID to search:"
  
  option "*" {
    label = "Search"
    goto  = "PerformUserSearch"
  }
}

action "PerformUserSearch" {
  type       = "http_call"
  url        = "/api/users/{{session.input}}"
  on_success = "UserFound"
  on_error   = "UserNotFound"
}

menu "UserFound" {
  text = "User: {{response.name}}\nStatus: {{response.status}}"
  # Terminal - no options
}

Best Practices for Open-Ended Input

Always provide clear instructions: Tell users exactly what format is expected.
Use confirmation menus: Let users verify their input before processing.
Handle validation on backend: For complex validation (phone formats, amount ranges), validate in your API and return appropriate error messages.
Provide re-entry options: If input is invalid, allow users to try again.

Deployment

Deploy a New Application

Code
curl -X POST https://api.tech231apps.net/api/v1/ussd/deploy \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "app \"MyApp\" {\n  shortcode = \"*123#\"\n  version = \"1.0.0\"\n  start = \"Main\"\n}\n\nmenu \"Main\" {\n  text = \"Welcome!\"\n}"
  }'

Response (Success):


Code
{
  "success": true,
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "applicationName": "MyApp",
  "version": "1.0.0",
  "status": "Active",
  "deployedAt": "2025-11-25T12:00:00Z"
}

Update an Existing Application

Code
curl -X PUT https://api.tech231apps.net/api/v1/ussd/deploy/MyApp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "app \"MyApp\" {\n  shortcode = \"*123#\"\n  version = \"1.1.0\"\n  start = \"Main\"\n}\n..."
  }'

Get Application Status

Code
curl -X GET https://api.tech231apps.net/api/v1/ussd/deploy/MyApp \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:


Code
{
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "MyApp",
  "shortCode": "*123#",
  "version": "1.1.0",
  "status": "Active",
  "deployedAt": "2025-11-25T12:00:00Z",
  "lastUpdatedAt": "2025-11-25T14:30:00Z"
}

Remove an Application

Code
curl -X DELETE https://api.tech231apps.net/api/v1/ussd/deploy/MyApp \
  -H "Authorization: Bearer YOUR_TOKEN"

Error Handling

Parse Errors

If your DSL has syntax errors, you'll receive details about the problem:


Code
{
  "success": false,
  "errors": [
    {
      "code": "PARSE_ERROR",
      "message": "Expected '}' at line 5, column 1",
      "line": 5,
      "column": 1
    }
  ]
}

Validation Errors

Semantic errors are caught during validation:


Code
{
  "success": false,
  "errors": [
    {
      "code": "INVALID_GOTO",
      "message": "Target menu 'NonExistent' does not exist"
    }
  ]
}

Common Error Codes

Code	Meaning	Solution
`PARSE_ERROR`	Syntax error in DSL	Check syntax at the reported line/column
`INVALID_START`	Start menu doesn't exist	Ensure the `start` value matches a menu name
`INVALID_GOTO`	Option target doesn't exist	Check that all `goto` values reference existing menus/actions
`CIRCULAR_REF`	Circular navigation detected	Remove infinite loops in navigation
`DUPLICATE_NAME`	Block name used twice	Use unique names for all menus and actions

Complete Examples

Code
app "CustomerSupport" {
  shortcode = "*456#"
  version   = "1.0.0"
  start     = "Welcome"
}

menu "Welcome" {
  text = "Welcome to Support!"
  
  option "1" {
    label = "Account Issues"
    goto  = "AccountIssues"
  }
  
  option "2" {
    label = "Billing"
    goto  = "BillingMenu"
  }
  
  option "3" {
    label = "Technical Help"
    goto  = "TechHelp"
  }
  
  option "4" {
    label = "Speak to Agent"
    goto  = "AgentConnect"
  }
}

menu "AccountIssues" {
  text = "Account Issues"
  
  option "1" {
    label = "Reset Password"
    goto  = "PasswordReset"
  }
  
  option "2" {
    label = "Update Details"
    goto  = "UpdateDetails"
  }
  
  option "3" {
    label = "Close Account"
    goto  = "CloseAccount"
  }
  
  option "0" {
    label = "Back"
    goto  = "Welcome"
  }
}

menu "PasswordReset" {
  text = "A password reset link has been sent to your registered email."
  
  option "0" {
    label = "Main Menu"
    goto  = "Welcome"
  }
}

# ... additional menus

Survey Application

Code
app "CustomerSurvey" {
  shortcode = "*789#"
  version   = "1.0.0"
  start     = "Intro"
}

menu "Intro" {
  text = "Help us improve! Take our 3-question survey."
  
  option "1" {
    label = "Start"
    goto  = "Question1"
  }
  
  option "2" {
    label = "Exit"
    goto  = "ThankYou"
  }
}

menu "Question1" {
  text = "Q1: How satisfied are you with our service?"
  
  option "1" {
    label = "Very Satisfied"
    goto  = "Question2"
  }
  
  option "2" {
    label = "Satisfied"
    goto  = "Question2"
  }
  
  option "3" {
    label = "Neutral"
    goto  = "Question2"
  }
  
  option "4" {
    label = "Dissatisfied"
    goto  = "Question2"
  }
}

menu "Question2" {
  text = "Q2: Would you recommend us?"
  
  option "1" {
    label = "Yes"
    goto  = "Question3"
  }
  
  option "2" {
    label = "Maybe"
    goto  = "Question3"
  }
  
  option "3" {
    label = "No"
    goto  = "Question3"
  }
}

menu "Question3" {
  text = "Q3: How often do you use our service?"
  
  option "1" {
    label = "Daily"
    goto  = "ThankYou"
  }
  
  option "2" {
    label = "Weekly"
    goto  = "ThankYou"
  }
  
  option "3" {
    label = "Monthly"
    goto  = "ThankYou"
  }
  
  option "4" {
    label = "Rarely"
    goto  = "ThankYou"
  }
}

menu "ThankYou" {
  text = "Thank you for your feedback! Your responses help us serve you better."
}

API Reference

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/ussd/deploy`	Deploy a new application
`PUT`	`/api/v1/ussd/deploy/{name}`	Update an existing application
`GET`	`/api/v1/ussd/deploy/{name}`	Get application metadata
`DELETE`	`/api/v1/ussd/deploy/{name}`	Remove an application

Authentication

All endpoints require authentication. Include your API token in the Authorization header:

Code
Authorization: Bearer YOUR_API_TOKEN

Rate Limits

Operation	Limit
Deploy/Update	10 requests per minute
Get Metadata	100 requests per minute
Delete	5 requests per minute

Need Help?

Technical Support: support@tech231apps.net
API Status: status.tech231apps.net
Documentation: docs.tech231apps.net

Last modified on January 26, 2026

Data-Driven Menus USSD DSL Actions Reference

Build & Test

USSD Application DSL Guide

Build interactive USSD applications using our simple, declarative domain-specific language (DSL). Define menus, actions, and navigation flows without writing code.

Quick Start

Here's a complete example of a simple banking USSD application:

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

menu "MainMenu" {
  text = "Welcome to MyBank! Select an option:"
  
  option "1" {
    label = "Check Balance"
    goto  = "CheckBalance"
  }
  
  option "2" {
    label = "Transfer Money"
    goto  = "TransferMenu"
  }
  
  option "3" {
    label = "Buy Airtime"
    goto  = "AirtimeMenu"
  }
}

menu "CheckBalance" {
  text = "Your balance is: $500.00"
  
  option "0" {
    label = "Main Menu"
    goto  = "MainMenu"
  }
}

menu "TransferMenu" {
  text = "Enter recipient phone number:"
  
  option "0" {
    label = "Cancel"
    goto  = "MainMenu"
  }
}

menu "AirtimeMenu" {
  text = "Select airtime amount:"
  
  option "1" {
    label = "$5"
    goto  = "ConfirmAirtime"
  }
  
  option "2" {
    label = "$10"
    goto  = "ConfirmAirtime"
  }
  
  option "0" {
    label = "Back"
    goto  = "MainMenu"
  }
}

menu "ConfirmAirtime" {
  text = "Airtime purchased successfully!\n\nPress 0 to return."
  
  option "0" {
    label = "Main Menu"
    goto  = "MainMenu"
  }
}

DSL Syntax

Application Block

Every USSD application starts with an app block that defines metadata:

Code
app "ApplicationName" {
  shortcode = "*123#"    # USSD short code
  version   = "1.0.0"    # Semantic version
  start     = "MainMenu" # First screen to show
}

Property	Required	Description
`shortcode`	Yes	The USSD code users dial (e.g., `123#`, `555*1#`)
`version`	Yes	Semantic version for tracking changes
`start`	Yes	Name of the first menu to display

Menus display text and options to users:

Code
menu "MenuName" {
  text = "Display this text to the user"
  
  option "1" {
    label = "Option description"
    goto  = "NextMenu"
  }
  
  option "2" {
    label = "Another option"
    goto  = "AnotherMenu"
  }
}

Property	Required	Description
`text`	Yes	Message displayed to the user
`option`	No	Navigation options (can have multiple)

Option Properties

Property	Required	Description
`label`	Yes	Description shown to user
`goto`	Yes	Target menu or action name

Action Blocks

Actions perform operations like API calls:

Code
action "Finance.CheckBalance" {
  type = "http_call"
  
  url     = "https://api.mybank.com/balance"
  method  = "GET"
  timeout = 30
  
  on_success = "BalanceResult"
  on_error   = "ErrorMenu"
}

Property	Required	Description
`type`	Yes	Action type (currently `http_call`)
`url`	Yes	API endpoint URL
`method`	No	HTTP method (default: `GET`)
`timeout`	No	Timeout in seconds (default: `30`)
`on_success`	Yes	Menu to show on success
`on_error`	Yes	Menu to show on error

Application Configuration

New in v2.0 — Configure global settings for HTTP calls, environment variables, and authentication.

Applications can define global configuration that applies to all actions:

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

  options {
    http_base_url = "https://api.mybank.com/v1"
    secrets_engine = {
      provider = "tenant_vault"
      path     = "tenants/{{org.id}}/apps/{{app.name}}"
    }
  }

  env = {
    API_KEY     = "{{secrets.api_key}}"
    ENVIRONMENT = "production"
    TIMEOUT     = "30"
  }

  auth {
    type     = "api_key"
    header   = "X-API-Key"
    value    = "{{env.API_KEY}}"
  }

  menu "MainMenu" { ... }
}

Options Block

Configure global HTTP and secrets settings:

Property	Required	Description
`http_base_url`	No	Base URL for relative `http_call` URLs
`secrets_engine`	No	Tenant-scoped secrets provider configuration

When http_base_url is set, actions can use relative URLs:

Code
# With http_base_url = "https://api.mybank.com/v1"
action "GetBalance" {
  type = "http_call"
  url  = "/accounts/balance"  # Resolves to https://api.mybank.com/v1/accounts/balance
}

Environment Variables (env)

Define environment variables accessible via {{env.*}} templates:

Code
env = {
  API_KEY     = "{{secrets.api_key}}"
  RETRY_COUNT = "3"
  DEBUG_MODE  = "false"
}

Use in actions:

Code
action "CallAPI" {
  type    = "http_call"
  url     = "{{options.http_base_url}}/data"
  timeout = "{{env.RETRY_COUNT}}"
}

Authentication (auth)

Configure global authentication applied to all HTTP calls:

Basic Authentication:

Code
auth {
  type     = "basic"
  username = "api_user"
  password = "{{secrets.api_password}}"
}

API Key Authentication:

Code
auth {
  type        = "api_key"
  header      = "X-API-Key"        # Use header-based auth
  # query_param = "api_key"        # Or use query parameter
  value       = "{{env.API_KEY}}"
}

OAuth2 Client Credentials:

Code
auth {
  type          = "oauth2_client_credentials"
  token_url     = "https://auth.mybank.com/oauth/token"
  client_id     = "{{secrets.client_id}}"
  client_secret = "{{secrets.client_secret}}"
  scope         = "read:accounts write:transfers"
}

Per-Action Auth Override

Override or disable authentication for specific actions:

Code
# Override with different auth
action "PublicEndpoint" {
  type = "http_call"
  url  = "/public/status"
  auth = "none"  # Disable auth for this action
}

action "AdminEndpoint" {
  type = "http_call"
  url  = "/admin/config"
  auth {
    type     = "basic"
    username = "admin"
    password = "{{secrets.admin_password}}"
  }
}

New in v2.1 — Configure consistent Back and Home keys across all menus.

The global_actions block enables navigation shortcuts that work from any menu:

Code
options {
  http_base_url = "https://api.mybank.com/v1"
  
  global_actions {
    back_key = "0"    # Press 0 to go back anywhere
    home_key = "99"   # Press 99 to return to start menu
  }
}

Property	Required	Description
`back_key`	No	Key that returns to the previous menu in navigation history
`home_key`	No	Key that returns to the application's `start` menu

Global actions are checked before menu-specific options, ensuring consistent behavior across all menus. See Navigation & Terminal Menus for detailed examples.

Comments

Add comments using # or //:

Code
# This is a comment
// This is also a comment

app "MyApp" {
  shortcode = "*123#"  # Inline comment
  version   = "1.0.0"
  start     = "Main"
}

Action Chains and Actions

Code
menu "TransferMenu" {
  text = "Enter amount to transfer:"

  option "*" {
    label = "Any amount"
    goto  = "ConfirmTransfer"
    actions = [
      {
        name   = "normalize-amount"
        type   = "string"
        op     = "trim"
        inputs = ["{{session.input}}"]
        target = "amount"
      },
      {
        name   = "amount-range"
        type   = "validate"
        source = "amount"
        min    = 1
        max    = 10000
      }
    ]
    error_target = "InvalidAmount"
    transactional = true
  }
}

For full details on action chains, inline action fields, and error handling, see:

Legacy Action Blocks (Compatibility)

Legacy action blocks are still parsed for backward compatibility, but new work should prefer inline action chains.

Code
action "Account.GetBalance" {
  type = "http_call"
  url  = "https://api.example.com/balance"
  on_success = "BalanceResult"
  on_error   = "ErrorScreen"
}

Template Variables

Updated: January 2025 - Added env.*, options.*, and secrets.* variables

Use double curly braces {{...}} to insert dynamic values:

Variable	Description	Example
`{{session.msisdn}}`	User's phone number	`+231886123456`
`{{session.id}}`	Current session ID	`sess_abc123`
`{{session.shortcode}}`	USSD shortcode dialed	`*123#`
`{{session.input}}`	User's last input	`1`
`{{session.networkid}}`	Mobile network identifier	`orange-lr`
`{{session.data.*}}`	Stored session data	`{{session.data.amount}}`
`{{response.*}}`	API response fields	`{{response.balance}}`
`{{response.nested.path}}`	Nested API response data	`{{response.user.name}}`
`{{config.*}}`	Application config	`{{config.api_key}}`
`{{env.*}}`	Environment variables from `env` block	`{{env.API_KEY}}`
`{{options.http_base_url}}`	Global HTTP base URL	`https://api.example.com`
`{{secrets.*}}`	Tenant-scoped secrets (requires `secrets_engine`)	`{{secrets.api_key}}`
`{{org.id}}`	Current tenant/organization ID	`org_abc123`
`{{app.name}}`	Application name	`MyBankingApp`

Best Practices

1. Always Provide a Back Option

Code
menu "SubMenu" {
  text = "Select an option:"
  
  option "1" {
    label = "Do something"
    goto  = "Action"
  }
  
  option "0" {
    label = "Back"      # Always include a way back
    goto  = "MainMenu"
  }
}

2. Use Descriptive Names

Code
# Good - clear and descriptive
menu "AccountBalanceResult" { ... }
action "Finance.TransferFunds" { ... }

# Avoid - unclear
menu "Menu1" { ... }
action "Action2" { ... }

3. Organize Actions with Dot Notation

Group related actions using dot notation:

Code
action "Finance.CheckBalance" { ... }
action "Finance.TransferFunds" { ... }
action "Finance.ViewHistory" { ... }

action "Airtime.Purchase" { ... }
action "Airtime.CheckBundle" { ... }

USSD screens have character limits (typically 160-182 characters). Keep messages short:

Code
# Good - concise
menu "Balance" {
  text = "Balance: $500.00"
  
  option "0" {
    label = "Back"
    goto  = "MainMenu"
  }
}

# Avoid - too long
menu "Balance" {
  text = "Your current account balance as of today is five hundred dollars and zero cents. Please press 0 to return to the main menu or press 1 to view transaction history."
}

5. Version Your Applications

Use semantic versioning to track changes:

Code
app "MyApp" {
  version = "1.0.0"  # Initial release
  # version = "1.1.0"  # New feature added
  # version = "2.0.0"  # Breaking changes
}

New in v2.1 — Enhanced navigation controls with Back/Home actions and terminal menus.

Menus can reference their parent menus to enable Back navigation. Unlike action-only cycles, menu-to-menu references are safe because they require explicit user input to traverse.

Code
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"
  }
  
  option "0" {
    label = "Back"
    goto  = "MainMenu"    # Safe: Requires user input to navigate back
  }
}

menu "BalanceMenu" {
  text = "Your balance: $100.00"
  
  option "0" {
    label = "Back"
    goto  = "ServicesMenu"  # Safe: Multi-level back navigation
  }
}

Configure consistent Back and Home keys across all menus using the global_actions block in your app options:

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

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

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"
  }
}

menu "BalanceMenu" {
  text = "Your balance: $100.00"
  # No explicit Back option needed - user presses 0 globally
}

With global_actions configured:

Back key (0): Returns to the previous menu in navigation history
Home key (99): Returns to the application's start menu

Global actions are checked before menu-specific options, so they work consistently across all menus. When the user is already at the start menu, the Back key has no effect (nowhere to go back to).

Terminal Menus

Terminal menus end the USSD session after displaying content. There are two ways to create terminal menus:

1. Empty Options (Implicit Terminal)

A menu with no options automatically ends the session:

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

2. Explicit Terminal Flag

Use terminal = true for menus that should end the session even if they have options defined for other purposes:

Code
menu "TransferComplete" {
  text = "Transfer successful!\nAmount: ${{session.data.amount}}\nRecipient: {{session.data.recipient}}"
  terminal = true  # Session ends after displaying this message
}

Property	Type	Default	Description
`terminal`	boolean	`false`	When `true`, the menu ends the session regardless of defined options

Terminal Search Results

Search result menus commonly use the terminal pattern to display results and end the session:

Code
menu "SearchInput" {
  text = "Enter phone number to search:"
  
  option "*" {
    label = "Search"
    goto  = "PerformSearch"
  }
}

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

menu "SearchResult" {
  text = "Search Result:\nName: {{response.name}}\nStatus: {{response.status}}"
  # No options = terminal, session ends after showing result
}

menu "SearchError" {
  text = "Search failed. Please try again later."
  terminal = true  # Explicit terminal for error state
}

Use global_actions for consistency: Configure Back/Home keys once instead of repeating in every menu.
Don't mix global and explicit Back options: If using global_actions, omit explicit Back options to avoid confusion or conflicts.
Terminal menus for confirmations: Use terminal menus for success/error messages where no further action is needed.
Test deep navigation: Ensure Back navigation works correctly through multiple menu levels.
Consider Home for deep menus: For apps with many levels, provide a Home key so users can quickly restart.

Open-Ended User Input

Tip: Use wildcard options to capture free-form user input like names, amounts, or phone numbers.

Wildcard Options

The wildcard selector (*) matches any input that doesn't match a specific option:

Code
menu "EnterPhone" {
  text = "Enter phone number:"
  
  option "*" {
    label = "Any input"
    goto  = "ConfirmPhone"
  }
}

menu "ConfirmPhone" {
  text = "You entered: {{session.input}}"
  
  option "1" {
    label = "Confirm"
    goto  = "ProcessPhone"
  }
  
  option "2" {
    label = "Re-enter"
    goto  = "EnterPhone"
  }
}

The user's input is automatically available via {{session.input}} in the next menu or action.

Combining Wildcards with Specific Options

You can mix wildcard with specific options. Specific options are matched first:

Code
menu "AmountEntry" {
  text = "Enter amount or select:"
  
  option "1" {
    label = "$10"
    goto  = "ConfirmTransfer"
  }
  
  option "2" {
    label = "$20"
    goto  = "ConfirmTransfer"
  }
  
  option "3" {
    label = "$50"
    goto  = "ConfirmTransfer"
  }
  
  option "*" {
    label = "Custom amount"
    goto  = "ValidateAmount"
  }
}

When user enters "1", "2", or "3", the specific option is matched. Any other input (like "75" or "100") triggers the wildcard.

Using Input in API Calls

Pass captured input to backend APIs:

Code
menu "SearchUser" {
  text = "Enter user ID to search:"
  
  option "*" {
    label = "Search"
    goto  = "PerformUserSearch"
  }
}

action "PerformUserSearch" {
  type       = "http_call"
  url        = "/api/users/{{session.input}}"
  on_success = "UserFound"
  on_error   = "UserNotFound"
}

menu "UserFound" {
  text = "User: {{response.name}}\nStatus: {{response.status}}"
  # Terminal - no options
}

Best Practices for Open-Ended Input

Always provide clear instructions: Tell users exactly what format is expected.
Use confirmation menus: Let users verify their input before processing.
Handle validation on backend: For complex validation (phone formats, amount ranges), validate in your API and return appropriate error messages.
Provide re-entry options: If input is invalid, allow users to try again.

Deployment

Deploy a New Application

Code
curl -X POST https://api.tech231apps.net/api/v1/ussd/deploy \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "app \"MyApp\" {\n  shortcode = \"*123#\"\n  version = \"1.0.0\"\n  start = \"Main\"\n}\n\nmenu \"Main\" {\n  text = \"Welcome!\"\n}"
  }'

Response (Success):


Code
{
  "success": true,
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "applicationName": "MyApp",
  "version": "1.0.0",
  "status": "Active",
  "deployedAt": "2025-11-25T12:00:00Z"
}

Update an Existing Application

Code
curl -X PUT https://api.tech231apps.net/api/v1/ussd/deploy/MyApp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "app \"MyApp\" {\n  shortcode = \"*123#\"\n  version = \"1.1.0\"\n  start = \"Main\"\n}\n..."
  }'

Get Application Status

Code
curl -X GET https://api.tech231apps.net/api/v1/ussd/deploy/MyApp \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:


Code
{
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "MyApp",
  "shortCode": "*123#",
  "version": "1.1.0",
  "status": "Active",
  "deployedAt": "2025-11-25T12:00:00Z",
  "lastUpdatedAt": "2025-11-25T14:30:00Z"
}

Remove an Application

Code
curl -X DELETE https://api.tech231apps.net/api/v1/ussd/deploy/MyApp \
  -H "Authorization: Bearer YOUR_TOKEN"

Error Handling

Parse Errors

If your DSL has syntax errors, you'll receive details about the problem:


Code
{
  "success": false,
  "errors": [
    {
      "code": "PARSE_ERROR",
      "message": "Expected '}' at line 5, column 1",
      "line": 5,
      "column": 1
    }
  ]
}

Validation Errors

Semantic errors are caught during validation:


Code
{
  "success": false,
  "errors": [
    {
      "code": "INVALID_GOTO",
      "message": "Target menu 'NonExistent' does not exist"
    }
  ]
}

Common Error Codes

Code	Meaning	Solution
`PARSE_ERROR`	Syntax error in DSL	Check syntax at the reported line/column
`INVALID_START`	Start menu doesn't exist	Ensure the `start` value matches a menu name
`INVALID_GOTO`	Option target doesn't exist	Check that all `goto` values reference existing menus/actions
`CIRCULAR_REF`	Circular navigation detected	Remove infinite loops in navigation
`DUPLICATE_NAME`	Block name used twice	Use unique names for all menus and actions

Complete Examples

Code
app "CustomerSupport" {
  shortcode = "*456#"
  version   = "1.0.0"
  start     = "Welcome"
}

menu "Welcome" {
  text = "Welcome to Support!"
  
  option "1" {
    label = "Account Issues"
    goto  = "AccountIssues"
  }
  
  option "2" {
    label = "Billing"
    goto  = "BillingMenu"
  }
  
  option "3" {
    label = "Technical Help"
    goto  = "TechHelp"
  }
  
  option "4" {
    label = "Speak to Agent"
    goto  = "AgentConnect"
  }
}

menu "AccountIssues" {
  text = "Account Issues"
  
  option "1" {
    label = "Reset Password"
    goto  = "PasswordReset"
  }
  
  option "2" {
    label = "Update Details"
    goto  = "UpdateDetails"
  }
  
  option "3" {
    label = "Close Account"
    goto  = "CloseAccount"
  }
  
  option "0" {
    label = "Back"
    goto  = "Welcome"
  }
}

menu "PasswordReset" {
  text = "A password reset link has been sent to your registered email."
  
  option "0" {
    label = "Main Menu"
    goto  = "Welcome"
  }
}

# ... additional menus

Survey Application

Code
app "CustomerSurvey" {
  shortcode = "*789#"
  version   = "1.0.0"
  start     = "Intro"
}

menu "Intro" {
  text = "Help us improve! Take our 3-question survey."
  
  option "1" {
    label = "Start"
    goto  = "Question1"
  }
  
  option "2" {
    label = "Exit"
    goto  = "ThankYou"
  }
}

menu "Question1" {
  text = "Q1: How satisfied are you with our service?"
  
  option "1" {
    label = "Very Satisfied"
    goto  = "Question2"
  }
  
  option "2" {
    label = "Satisfied"
    goto  = "Question2"
  }
  
  option "3" {
    label = "Neutral"
    goto  = "Question2"
  }
  
  option "4" {
    label = "Dissatisfied"
    goto  = "Question2"
  }
}

menu "Question2" {
  text = "Q2: Would you recommend us?"
  
  option "1" {
    label = "Yes"
    goto  = "Question3"
  }
  
  option "2" {
    label = "Maybe"
    goto  = "Question3"
  }
  
  option "3" {
    label = "No"
    goto  = "Question3"
  }
}

menu "Question3" {
  text = "Q3: How often do you use our service?"
  
  option "1" {
    label = "Daily"
    goto  = "ThankYou"
  }
  
  option "2" {
    label = "Weekly"
    goto  = "ThankYou"
  }
  
  option "3" {
    label = "Monthly"
    goto  = "ThankYou"
  }
  
  option "4" {
    label = "Rarely"
    goto  = "ThankYou"
  }
}

menu "ThankYou" {
  text = "Thank you for your feedback! Your responses help us serve you better."
}

API Reference

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/ussd/deploy`	Deploy a new application
`PUT`	`/api/v1/ussd/deploy/{name}`	Update an existing application
`GET`	`/api/v1/ussd/deploy/{name}`	Get application metadata
`DELETE`	`/api/v1/ussd/deploy/{name}`	Remove an application

Authentication

All endpoints require authentication. Include your API token in the Authorization header:

Code
Authorization: Bearer YOUR_API_TOKEN

Rate Limits

Operation	Limit
Deploy/Update	10 requests per minute
Get Metadata	100 requests per minute
Delete	5 requests per minute

Need Help?

Technical Support: support@tech231apps.net
API Status: status.tech231apps.net
Documentation: docs.tech231apps.net

Last modified on January 26, 2026

Data-Driven Menus USSD DSL Actions Reference

Quick Start

DSL Syntax

Application Block

Menu Blocks

Option Properties

Action Blocks

Application Configuration

Options Block

Environment Variables (env)

Authentication (auth)

Per-Action Auth Override

Global Navigation Actions

Comments

Action Chains and Actions

Legacy Action Blocks (Compatibility)

Template Variables

Best Practices

1. Always Provide a Back Option

2. Use Descriptive Names

3. Organize Actions with Dot Notation

4. Keep Menu Text Concise

5. Version Your Applications

Navigation & Terminal Menus

Back Navigation

Global Navigation Actions

Terminal Menus

Terminal Search Results

Navigation Best Practices

Open-Ended User Input

Wildcard Options

Combining Wildcards with Specific Options

Using Input in API Calls

Best Practices for Open-Ended Input

Deployment

Deploy a New Application

Update an Existing Application

Get Application Status

Remove an Application

Error Handling

Parse Errors

Validation Errors

Common Error Codes

Complete Examples

Customer Support Menu

Survey Application

API Reference

Endpoints

Authentication

Rate Limits

Need Help?

Quick Start

DSL Syntax

Application Block

Menu Blocks

Option Properties

Action Blocks

Application Configuration

Options Block

Environment Variables (env)

Authentication (auth)

Per-Action Auth Override

Global Navigation Actions

Comments

Action Chains and Actions

Legacy Action Blocks (Compatibility)

Template Variables

Best Practices

1. Always Provide a Back Option

2. Use Descriptive Names

3. Organize Actions with Dot Notation

4. Keep Menu Text Concise

5. Version Your Applications

Navigation & Terminal Menus

Back Navigation

Global Navigation Actions

Terminal Menus

Terminal Search Results

Navigation Best Practices

Open-Ended User Input

Wildcard Options