Skip to main content

USSD Best Practices

USSD works on every phone, no data or app required — making it the broadest reach channel in Africa. But sessions are short-lived and screens are tiny. This guide covers the design principles that keep USSD usable.

🚀 Quick Start​

A USSD request hits your webhook; you reply with CON (continue) or END (terminate).

# Incoming request body from the gateway
{ "session_id": "ussd_abc", "phone": "+254712345678", "text": "" }

# Your response (plain text)
CON Welcome to Acme
1. Check balance
2. Buy airtime

📏 Screen & Text Limits​

Feature phones show very little. Keep every screen tight.

ConstraintLimit
Characters per screen~160
Menu options per screen5 or fewer
Session duration~20–180s (carrier-set)
Menu depth3 levels max

🧭 Menu Design​

def main_menu():
    return ("CON Welcome to Acme\n"
            "1. Balance\n"
            "2. Buy airtime\n"
            "3. Send money\n"
            "0. Exit")
function render(text) {
  if (text === '') return 'CON Welcome to Acme\n1. Balance\n2. Buy airtime';
  if (text === '1') return 'END Your balance is KES 240.';
  return 'END Invalid choice.';
}
  • Put the most-used option first.
  • Use single digits for selection.
  • Reserve 0 for back/exit consistently.
  • End the session as soon as the task is done (END).

⏱️ Timeouts​

Sessions expire fast and silently. Design so every step is completable in seconds:

  • Ask for one input per screen.
  • Avoid long free-text entry — use numbered choices.
  • Persist progress so a re-dial can resume where sensible.

💡 Best Practices​

  • Keep menus shallow — 3 levels maximum.
  • One question per screen to fit the timeout.
  • Use consistent navigation (0 = back/exit) across all menus.
  • Confirm money-moving actions with an explicit yes/no screen.
  • Respond fast — gateways drop slow webhook replies.
  • Localize by letting the first screen pick a language.

⚠️ Common Pitfalls​

  • Overflowing a screen past ~160 chars — text gets cut off.
  • Long text input that users can't complete before timeout.
  • Deep nested menus that lose the user.

📚 Related Resources​

Last Updated: May 2026