Spring Boot USSD Demo
A Java reference implementation showing how to build USSD menu services with Spring Boot — covering both simple single-level flows and complex branching menus with session state.
@PostMapping("/ussd")
public ResponseEntity<String> ussd(
@RequestParam String sessionId,
@RequestParam String serviceCode,
@RequestParam String phoneNumber,
@RequestParam String text
) {
String response = ussdService.processRequest(
sessionId, serviceCode, phoneNumber, text
);
return ResponseEntity.ok(response);
}Why this exists
USSD development resources in Java are sparse. Most tutorials cover only the simplest case — a single menu with no state. Real services need to remember where a user is across multiple interactions.
This demo was built to fill that gap: a clean, well-structured reference that developers can fork and extend rather than starting from scratch.
Who it's for
Java developers building their first USSD service, or teams evaluating whether Spring Boot is a good fit for a USSD project. It's also useful as a starting point for anyone integrating with Africa's Talking.
Five developers have starred the repository — a small but specific audience that found it useful.
What's covered
Simple flow
A straightforward single-level USSD menu — the foundation most services start with. Good reference for understanding the request/response cycle.
Complex flow
A multi-level menu with branching paths, user input handling, and session state — closer to what a real banking or information service looks like.
Session caching
Uses caching to track where a user is in the menu tree across multiple USSD requests within a single session.
Africa's Talking compatible
Designed around the Africa's Talking USSD gateway — the same gateway used by M-Pesa, Airtel Money, and hundreds of other services.
Spring Boot foundation
Built on Spring Boot, making it easy to extend with additional services, databases, or business logic from the Java ecosystem.
Open source reference
5 stars on GitHub. Used by developers learning USSD or setting up their first USSD service in Java.