USSD overview

USSD lets customers interact with your service from any phone, with no app and no data plan. A user dials a short code (e.g. *384*123#), the session begins, and they navigate a menu with their keypad.

How it works

1. A user dials your short code.
2. Your application receives a session request with their phone number and network.
3. Your application replies with menu text and up to 4 numbered options.
4. The user presses a number; your application replies again.
5. This continues until the session is terminated or times out.

Key concepts

• Short code: the dial number allocated to your service, e.g. *384*123#.
• Session ID: uniquely identifies one USSD session.
• Network: Safaricom, Airtel or Telkom. Some behaviour differs per operator.
• Session timeout: if the user stops responding, the session closes.

Building a menu

Reply with text and options in this format:

Welcome to MyService
1. Check balance
2. Buy airtime
3. Talk to support

You can also send a terminating response (no options) to end the session, and prompt for free-form input (such as an account number) instead of a menu.

Best practices

• Keep each menu screen to 160 characters or fewer.
• Always offer a way back or out (e.g. option 0 to exit).
• Validate free-form input before accepting it.
• Handle network timeouts gracefully: the user may have walked away mid-flow.

See also

• Billing: USSD sessions are billed per session
• Support: to request a short code for your service