Core Concepts

Understanding these concepts will help you build better USSD applications.

USSD Basics

USSD (Unstructured Supplementary Service Data) is a protocol used by GSM phones to communicate with service providers. Unlike SMS, USSD creates a real-time session.

Key Characteristics

• Session-based: Each interaction is part of a continuous session
• Real-time: Responses are instant, no store-and-forward
• Menu-driven: Users navigate by entering numbers
• Text-only: No images, limited to 182 characters per screen
• Timeout: Sessions expire after ~3 minutes of inactivity

Flows

A flow is a complete USSD application. It defines all the screens, logic, and data handling for your service.

In Studio, a flow looks like a flowchart:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Welcome   │ ──→ │  Get Name   │ ──→ │   Confirm   │
│   (Menu)    │     │   (Input)   │     │   (End)     │
└─────────────┘     └─────────────┘     └─────────────┘

Flow Properties

Nodes

Nodes are the building blocks of a flow. Each node represents a screen or action.

Node Types

Select an option:
1. Check Balance
2. Send Money

Enter phone number:

Processing your request...

Thank you for using our service!

Sessions

A session represents a single user interaction from dial to end.

Session Lifecycle

User dials *123# → Session created → Flow starts
       ↓
User enters "1" → Input processed → Next node
       ↓
User enters "2" → Input processed → Next node
       ↓
End node reached → Session terminated

Session States

Variables

Variables store data during a session. They can be:

• User input: Data entered by the user
• System variables: Phone number, session ID, timestamp
• API responses: Data fetched from external services

Using Variables

Reference variables in node content using ${variableName}:

Welcome, ${name}!
Your balance is ${balance} GHS.

System Variables

Providers

Providers are USSD gateways that connect your application to telecom networks. StarHash supports:

• Africa's Talking
• Hubtel
• Arkesel
• Nalo

Each provider has a different format. StarHash handles the translation automatically—you just design your flow once.

Next Steps