Basics

USSD DSL Getting Started

Getting Started with USSD DSL

Build interactive USSD applications using our simple, declarative domain-specific language (DSL). This guide walks you through creating your first application in under 10 minutes.

Prerequisites

Access to the Tech231 Platform API
An API token with USSD deployment permissions
A registered USSD shortcode for your tenant

Your First Application

Create the DSL file

Create a file called hello.ussd with this content:

Code
app "HelloWorld" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "Welcome"
}

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

  option "1" {
    label = "Say Hello"
    goto  = "Greeting"
  }

  option "2" {
    label = "Exit"
    goto  = "Goodbye"
  }
}

menu "Greeting" {
  text = "Hello, World! 👋"

  option "0" {
    label = "Back"
    goto  = "Welcome"
  }
}

menu "Goodbye" {
  text = "Thanks for visiting. Goodbye!"
  # No options = terminal menu, session ends
}

Understand the structure Every USSD application has three key components:

Block Purpose
app Application metadata (shortcode, version, start menu)
menu User-facing screens with text and options
action Backend operations (API calls, data processing)

Block	Purpose
`app`	Application metadata (shortcode, version, start menu)
`menu`	User-facing screens with text and options
`action`	Backend operations (API calls, data processing)

Deploy the application Use the deployment API to publish your application:

Code
curl -X POST https://api.tech231apps.net/api/v1/ussd/deploy \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @hello.ussd

Test it

Dial your shortcode (e.g., *123#) from a registered test device, or use the testing API:

Code
curl -X POST https://api.tech231apps.net/api/v1/ussd/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcode": "*123#",
    "msisdn": "+231886000001",
    "input": ""
  }'

Next Steps

Now that you have a basic application running, explore these topics:

Guide	Description
DSL Guide	Complete syntax reference and best practices
Action Chains	Execute multiple operations in sequence
Actions Reference	All 12 action types with examples
Template Variables	Dynamic content with session data
Data-Driven Menus	Build menus from API data

Quick Reference

Application Block

Code
app "AppName" {
  shortcode = "*123#"    # Required: USSD code
  version   = "1.0.0"    # Required: Semantic version
  start     = "MainMenu" # Required: First menu to display

  # Optional configuration
  options {
    http_base_url = "https://api.example.com"
    global_actions {
      back_key = "0"
      home_key = "99"
    }
  }

  # Optional environment variables
  env = {
    API_KEY = "{{secrets.api_key}}"
  }

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

Code
menu "MenuName" {
  text = "Display text to user"

  option "1" {
    label = "Option label"
    goto  = "NextMenu"
  }

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

Action Block

Code
action "GroupName.ActionName" {
  type = "http_call"
  url  = "/api/endpoint"
  
  on_success = "SuccessMenu"
  on_error   = "ErrorMenu"
}

Use dot notation (e.g., Finance.CheckBalance) to organize related actions into logical groups.

Last modified on February 6, 2026

OTP Integration Examples DSL Quick Reference

Your First Application

Create the DSL file

Create a file called hello.ussd with this content:

Code
app "HelloWorld" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "Welcome"
}

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

  option "1" {
    label = "Say Hello"
    goto  = "Greeting"
  }

  option "2" {
    label = "Exit"
    goto  = "Goodbye"
  }
}

menu "Greeting" {
  text = "Hello, World! 👋"

  option "0" {
    label = "Back"
    goto  = "Welcome"
  }
}

menu "Goodbye" {
  text = "Thanks for visiting. Goodbye!"
  # No options = terminal menu, session ends
}

Understand the structure Every USSD application has three key components:

Block Purpose
app Application metadata (shortcode, version, start menu)
menu User-facing screens with text and options
action Backend operations (API calls, data processing)

Block	Purpose
`app`	Application metadata (shortcode, version, start menu)
`menu`	User-facing screens with text and options
`action`	Backend operations (API calls, data processing)

Deploy the application Use the deployment API to publish your application:

Code
curl -X POST https://api.tech231apps.net/api/v1/ussd/deploy \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @hello.ussd

Test it

Dial your shortcode (e.g., *123#) from a registered test device, or use the testing API:

Code
curl -X POST https://api.tech231apps.net/api/v1/ussd/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcode": "*123#",
    "msisdn": "+231886000001",
    "input": ""
  }'

Next Steps

Now that you have a basic application running, explore these topics:

Guide

Description

DSL Guide

Complete syntax reference and best practices

Action Chains

Execute multiple operations in sequence

Actions Reference

All 12 action types with examples

Template Variables

Dynamic content with session data

Data-Driven Menus

Build menus from API data

Quick Reference

Application Block

Code

app "AppName" {
  shortcode = "*123#"    # Required: USSD code
  version   = "1.0.0"    # Required: Semantic version
  start     = "MainMenu" # Required: First menu to display

  # Optional configuration
  options {
    http_base_url = "https://api.example.com"
    global_actions {
      back_key = "0"
      home_key = "99"
    }
  }

  # Optional environment variables
  env = {
    API_KEY = "{{secrets.api_key}}"
  }

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

Code

menu "MenuName" {
  text = "Display text to user"

  option "1" {
    label = "Option label"
    goto  = "NextMenu"
  }

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

Action Block

Code

action "GroupName.ActionName" {
  type = "http_call"
  url  = "/api/endpoint"
  
  on_success = "SuccessMenu"
  on_error   = "ErrorMenu"
}

Use dot notation (e.g., Finance.CheckBalance) to organize related actions into logical groups.

Last modified on February 6, 2026

USSD DSL Getting Started

Getting Started with USSD DSL

Prerequisites

Your First Application

Next Steps

Quick Reference

Application Block

Menu Block

Action Block

USSD DSL Getting Started

Getting Started with USSD DSL

Prerequisites

Your First Application

Next Steps

Quick Reference

Application Block

Menu Block

Action Block