ussd-flow
A Python library that takes the complexity out of building USSD applications — the mobile menu systems used by hundreds of millions of people across Africa to access banking, health information, and government services without internet.
from ussdflow import CacheManager, IngressData, USSDService
cache = CacheManager(cache_type="redis", host="localhost", port=6379)
service = USSDService(
menu_file_path="menus.json",
cache_manager=cache
)
# Handle an incoming USSD request
response = service.ingress(IngressData(
session_id="abc123",
service_code="*123#",
phone_number="254712345678",
text=""
))What is USSD?
USSD (Unstructured Supplementary Service Data) is the technology behind those menu systems you access by dialling short codes like *123#. No internet needed — it works on any phone.
In Africa, USSD is infrastructure. M-Pesa runs on it. Government services run on it. Agricultural information systems run on it. For hundreds of millions of people, USSD is the internet.
Why I built this
Every USSD project I worked on required building the same things from scratch — session tracking, menu state, user flow logic. It was repetitive and error-prone.
I extracted the common patterns into a reusable library. Now you describe what your menus look like in a JSON file, and the library handles navigating them, remembering where users are, and talking to Africa's Talking.
What it does
Define menus as JSON
Instead of writing hundreds of lines of conditional logic, you describe your USSD screens in a simple JSON file. The library handles the rest.
Built-in session management
USSD sessions are stateful — the library manages this automatically using Redis, so you don't have to think about it.
Africa's Talking integration
Works out of the box with Africa's Talking, the most widely used USSD gateway in Africa.
Framework agnostic
Works with Django, FastAPI, and Flask. Drop it into whatever Python stack you're already using.
Published on PyPI
Install with a single command: pip install ussdflow. Used by other developers building mobile money and information services.
Open source
MIT licensed. Anyone can use it, contribute to it, and build on top of it.