Back to Blog

Using ngrok with Africa’s Talking USSD (Technical Walkthrough)

696a4edf0617153016f9e0d8•

Below is a technical, step-by-step guide for using ngrok with Africa’s Talking USSD, integrated with a CBS (Community-Based Surveillance) example.

Using ngrok with Africa’s Talking USSD (Technical Walkthrough)

Why ngrok?

Africa’s Talking requires a publicly accessible HTTPS endpoint to send USSD HTTP POST requests.
When developing locally (Flask / Express), ngrok securely exposes your local server to the internet.

Architecture (Local Development)

Mobile Phone / Simulator
        |
        v
Africa’s Talking USSD Gateway
        |
        v
     ngrok HTTPS URL
        |
        v
Local Server (Flask / Express)

1. Install ngrok

Linux / macOS

snap install ngrok
# or
brew install ngrok

Windows

Download from:

https://ngrok.com/download

2. Authenticate ngrok

  1. Create an account at ngrok.com
  2. Copy your auth token
  3. Run:
ngrok config add-authtoken YOUR_AUTH_TOKEN

3. Run Your USSD Application

Flask (Example)

python app.py

By default:

http://localhost:5000

Express (Node.js)

node index.js

Common ports:

  • Flask → 5000
  • Express → 3000

4. Expose Local Server with ngrok

Flask

ngrok http 5000

Express

ngrok http 3000

ngrok will generate a public HTTPS URL:

https://a1b2c3d4.ngrok-free.app

5. Configure Africa’s Talking USSD Callback

  1. Log in to Africa’s Talking
  2. Go to Sandbox
  3. Select USSD
  4. Set the Callback URL to:
https://a1b2c3d4.ngrok-free.app/ussd

⚠️ Always use HTTPS, not HTTP.

6. Test Using Africa’s Talking USSD Simulator

Open:

https://developers.africastalking.com/simulator
  • Select your USSD service code
  • Dial:
*384*XXX#

Requests will now hit:

ngrok → your local server

7. ngrok Request Inspection (Debugging)

Open ngrok web interface:

http://127.0.0.1:4040

You can:

  • Inspect incoming POST payloads
  • See headers and body
  • Debug malformed responses
  • Replay requests

This is extremely useful for USSD debugging.

8. CBS USSD Example (With ngrok in Mind)

Sample Flow

Dial *384*123#
↓
1. Report illness
↓
1. Fever
↓
END Thank you. Case reported.

Flask CBS Handler

@app.route("/ussd", methods=['POST'])
def ussd():
    text = request.values.get("text", "")
    phone_number = request.values.get("phoneNumber")

9. Common ngrok + USSD Issues

❌ Session Ends Immediately

  • Response does not start with CON or END
  • HTTP error returned

❌ No Requests Reaching Server

  • Wrong ngrok port
  • Callback URL mismatch
  • Local server not running

❌ Menus Not Displaying Properly

  • Special characters used
  • Long lines
  • Missing newline \n

10. ngrok Best Practices for USSD Development

  • Keep ngrok running while testing
  • Update Africa’s Talking callback URL when ngrok restarts
  • Use text/plain responses
  • Log all requests
  • Avoid heavy processing in USSD handlers
  • Store CBS reports asynchronously

11. Production Note

ngrok is for development only.

For production CBS systems:

  • Deploy to a public server (AWS, GCP, DigitalOcean)
  • Use a stable domain
  • Enable HTTPS
  • Add request validation and logging

Conclusion

ngrok enables rapid local development and testing of Africa’s Talking USSD applications. Combined with USSD simulators, it allows developers to quickly prototype and debug Community-Based Surveillance systems before deploying to production infrastructure.

This setup is ideal for building, testing, and validating CBS reporting workflows in real-world conditions.