Copy page

Basics

DSL Quick Reference

DSL Quick Reference

This page provides a comprehensive reference for all USSD DSL blocks, properties, and syntax patterns.

Application Block

The root block defining your USSD application.

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

  options { ... }  # Optional
  env = { ... }    # Optional
  auth { ... }     # Optional
}

Application Properties

Property	Required	Type	Description
shortcode	✅	string	USSD code users dial (e.g., *123#, *555*1#)
version	✅	string	Semantic version for tracking changes
start	✅	string	Name of the first menu to display
options	❌	block	Global configuration (HTTP, secrets, navigation)
env	❌	map	Environment variables accessible via {{env.*}}
auth	❌	block	Global authentication for HTTP calls

---

Options Block

Configure global application settings.

Code
options {
  http_base_url = "https://api.example.com/v1"

  secrets_engine = {
    provider = "tenant_vault"
    path     = "tenants/{{org.id}}/apps/{{app.name}}"
  }

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

Options Properties

Property	Type	Description
http_base_url	string	Base URL for relative HTTP action URLs
secrets_engine	block	Tenant-scoped secrets provider configuration
global_actions	block	Global Back/Home key configuration

Secrets Engine Properties

Property	Required	Description
provider	✅	Provider type (tenant_vault, azure_keyvault)
path	✅	Path template for secrets (supports {{org.id}}, {{app.name}})

Global Actions Properties

Property	Type	Description
back_key	string	Key that navigates back in history (e.g., "0")
home_key	string	Key that returns to start menu (e.g., "99")

---

Menu Block

User-facing screens that display text and capture input.

Code
menu "MenuName" {
  text = "Display text to the user"
  terminal = false  # Optional

  option "1" {
    label = "Option description"
    goto  = "NextMenu"
    actions = [ ... ]  # Optional action chain
  }

  option "*" {
    label = "Any input"
    goto  = "ProcessInput"
  }

  # Data-driven menus
  data_source { ... }
}

Menu Properties

Property	Required	Type	Description
text	✅	string	Message displayed to the user
terminal	❌	boolean	When true, ends session on display
option	❌	block(s)	Navigation options (can have multiple)
data_source	❌	block	Data-driven menu configuration

Option Properties

Property	Required	Type	Description
label	✅	string	Description shown to user
goto	✅	string	Target menu or action name
actions	❌	array	Action chain to execute before navigation
error_target	❌	string	Menu to navigate on action chain error
transactional	❌	boolean	Rollback on error (default: true)

Wildcard Option

Use "*" as the selector to match any input not matched by specific options:

Code
option "*" {
  label = "Custom amount"
  goto  = "ValidateAmount"
}

The user's input is available via {{session.input}}.

---

Action Block (Legacy)

Standalone action blocks for backward compatibility.

Code
action "GroupName.ActionName" {
  type = "http_call"
  url  = "/api/endpoint"
  method = "GET"
  
  headers = { "X-Custom" = "value" }
  body    = { "field" = "{{session.data.value}}" }
  
  response_map = {
    result = "$.data.result"
  }
  
  on_success = "SuccessMenu"
  on_error   = "ErrorMenu"
  
  auth = "none"  # Or auth block
}

Action Properties

Property	Required	Type	Description
type	✅	string	Action type (see Action Types below)
on_success	❌	string	Menu/block to navigate on success
on_error	❌	string	Menu/block to navigate on error
auth	❌	block/string	Per-action auth override ("none" to disable)

---

Authentication Block

Configure authentication for 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"      # Header-based
  value  = "{{env.API_KEY}}"
}

# Or query parameter
auth {
  type        = "api_key"
  query_param = "api_key"   # Query param-based
  value       = "{{env.API_KEY}}"
}

OAuth2 Client Credentials

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

Disable Authentication

Code
# On specific action
action "PublicEndpoint" {
  type = "http_call"
  url  = "/public/status"
  auth = "none"
}

---

Data Source Block

Configure data-driven menus that fetch options from an API.

Code
data_source {
  type   = "http"
  method = "GET"
  url    = "/products?category={{session.data.category}}"
  
  response_array_path = "data.items"
  
  display_template  = "{{name}} - ${{price}}"
  selected_variable = "selectedProduct"
  on_select         = "ProductDetail"
  
  page_size    = 5
  filter       = "status == 'active'"
  sort_by      = "price"
  sort_order   = "asc"
  limit        = 20
  
  empty_message = "No products found"
  empty_goto    = "EmptyResults"
  error_menu    = "LoadError"
  
  next_label     = "More"
  previous_label = "Back"
}

Data Source Properties

Property	Required	Default	Description
type	❌	"http"	Data source type
method	❌	"GET"	HTTP method
url	✅	-	Endpoint URL
response_array_path	❌	(root)	JSON path to array in response
display_template	✅	-	Template for option labels
selected_variable	❌	"selectedItem"	Session variable for selection
on_select	✅	-	Target menu when item selected
page_size	❌	5	Items per page
filter	❌	-	Filter expression
sort_by	❌	-	Field to sort by
sort_order	❌	"asc"	Sort direction ("asc", "desc")
limit	❌	-	Maximum items to fetch
empty_message	❌	"No items available"	Empty list message
empty_goto	❌	-	Auto-redirect on empty
error_menu	❌	-	Error navigation target
next_label	❌	"More"	Next page option label
previous_label	❌	"Previous"	Previous page option label
timeout_seconds	❌	30	Request timeout in seconds
retry_count	❌	2	Retry attempts on failure
retry_delay_ms	❌	500	Delay between retries (ms)

---

Action Types

Summary Table

Type	Aliases	Purpose	Key Fields
noop	-	No operation	-
set	-	Set variable value	target, value/source
inc	increment	Increment number	target, by
dec	decrement	Decrement number	target, by
delete	remove	Remove variable	target
env	environment	Get config value	key, target, fallback
arithmetic	add, subtract, multiply, divide, modulo	Math operations	op, left, right, target
conditional	if	Branching	lhs, op, rhs, true_target, false_target
switch	-	Multi-case routing	source, cases, default_target, target
string	concat, substring, upper, lower, trim, split, format	String operations	op, inputs, target
validate	-	Input validation	source, pattern/min/max
crypto	hash, encrypt, decrypt	Hash/encrypt	mode, input, target
http	http_call, api_call	HTTP requests	url, method, response_map
grpc	-	gRPC calls	client, method, request_fields
send_sms	-	Send SMS message	recipient, message, sender_id, target
send_otp	-	Send OTP	phone_number, purpose, expiry_minutes, sender_id, target

See Actions Reference for complete details.

---

Comments

Code
# Single line comment
// Also a single line comment

app "MyApp" {
  shortcode = "*123#"  # Inline comment
}

---

Full Example

Code
app "BankingDemo" {
  shortcode = "*231#"
  version   = "2.0.0"
  start     = "Welcome"

  options {
    http_base_url = "https://api.mybank.com/v1"
    global_actions {
      back_key = "0"
      home_key = "99"
    }
  }

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

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

menu "Welcome" {
  text = "Welcome to MyBank!\n\nSelect an option:"

  option "1" {
    label = "Check Balance"
    goto  = "Balance"
    actions = [
      {
        type   = "http"
        method = "GET"
        url    = "/accounts/{{session.msisdn}}/balance"
        response_map = { balance = "$.balance" }
      }
    ]
    error_target = "ErrorMenu"
  }

  option "2" {
    label = "Transfer"
    goto  = "TransferMenu"
  }
}

menu "Balance" {
  text = "Your balance: ${{session.data.balance}}"
  # User presses 0 (global back) to return to Welcome
}

menu "TransferMenu" {
  text = "Enter recipient number:"

  option "*" {
    label = "Phone number"
    goto  = "EnterAmount"
    actions = [
      {
        type    = "validate"
        source  = "{{session.input}}"
        pattern = "^\\d{10}$"
        target  = "recipient"
      }
    ]
    error_target = "InvalidPhone"
  }
}

menu "EnterAmount" {
  text = "Enter amount to send:"

  option "*" {
    label = "Amount"
    goto  = "ConfirmTransfer"
    actions = [
      {
        type   = "validate"
        source = "{{session.input}}"
        min    = 1
        max    = 10000
        target = "amount"
      }
    ]
    error_target = "InvalidAmount"
  }
}

menu "ConfirmTransfer" {
  text = "Send ${{session.data.amount}} to {{session.data.recipient}}?"

  option "1" {
    label = "Confirm"
    goto  = "TransferSuccess"
    actions = [
      {
        type   = "http"
        method = "POST"
        url    = "/transfers"
        body   = {
          "from"   = "{{session.msisdn}}"
          "to"     = "{{session.data.recipient}}"
          "amount" = "{{session.data.amount}}"
        }
      }
    ]
    error_target = "TransferFailed"
  }

  option "2" {
    label = "Cancel"
    goto  = "Welcome"
  }
}

menu "TransferSuccess" {
  text = "Transfer successful!\n\nThank you for using MyBank."
  terminal = true
}

menu "ErrorMenu" {
  text = "Something went wrong. Please try again later."
  terminal = true
}

menu "InvalidPhone" {
  text = "Invalid phone number. Must be 10 digits."

  option "0" {
    label = "Try again"
    goto  = "TransferMenu"
  }
}

menu "InvalidAmount" {
  text = "Invalid amount. Enter between $1 and $10,000."

  option "0" {
    label = "Try again"
    goto  = "EnterAmount"
  }
}

menu "TransferFailed" {
  text = "Transfer failed. Please check your balance and try again."
  terminal = true
}