Skip to main content

OLA USSD Gateway

A production-ready USSD gateway that normalizes telecom provider protocols and routes requests to your backend applications. Build USSD services without worrying about provider-specific implementation details.

What is OLA USSD Gateway?​

OLA USSD Gateway acts as a protocol adapter between telecom providers and your backend applications. It receives USSD requests from various providers (Movitel, Vodacom, Tmcel), normalizes them into a standard format, and forwards them to your application via HTTP callbacks.

Why Use OLA Gateway?​

🔄 Protocol Abstraction​

  • Multiple provider support: Movitel (SOAP/XML), Vodacom (XML), Tmcel (JSON)
  • Single integration point: Build once, work with all providers
  • No provider-specific code: Focus on your business logic

🚀 Simplified Development​

  • Standard HTTP callbacks: Your app receives clean JSON requests
  • Built-in session management: Automatic session tracking and cleanup
  • Backend registration: Simple API to register your backend services

📦 Production Ready​

  • Reliable routing: Service code-based routing (*365#, *105#, etc.)
  • Automatic retries: Configurable retry logic with exponential backoff
  • Health monitoring: Built-in health check endpoints

🔌 Flexible Architecture​

  • Multiple backends: Route different service codes to different apps
  • Any language: Build backends in Node.js, Python, Go, Java, or any HTTP-capable language
  • Scalable: Deploy multiple gateway instances behind a load balancer

How It Works​

1. Provider Request (Telecom Side)​

A user dials *365# on their phone. The telecom provider sends a request to the gateway in their specific protocol format.

2. Gateway Normalization​

The gateway normalizes all provider formats into a standard JSON format and forwards to your backend:

{
  "provider": "movitel",
  "msisdn": "258823456789",
  "session_id": "sess_123",
  "transaction_id": "txn_123",
  "input": "1"
}

3. Your Backend Response​

Your application processes the request and returns a standard response:

{
  "session_id": "sess_123",
  "transaction_id": "txn_123",
  "output": [
    "Welcome to MyBank USSD",
    "",
    "1. Check Balance",
    "2. Transfer Money",
    "0. Exit"
  ],
  "end_session": false
}

4. Provider Response​

The gateway converts your response back to the provider's expected format and sends it back. The user sees the menu on their phone.

Key Features​

Backend Registration​

Register your backend application via REST API:

POST /backends
{
  "callback_url": "http://your-app.com/ussd/callback",
  "service_code": "*365#",
  "name": "Banking Service",
  "timeout": 5,
  "retries": 2
}

Session Management​

  • Automatic session creation: Gateway creates sessions on first interaction
  • Configurable TTL: Default 5 minutes, extendable on each user input
  • Storage options: In-memory (default) or database-backed
  • Automatic cleanup: Expired sessions are automatically removed

Request Routing​

  • Service code matching: Route *365# to Backend A, *105# to Backend B
  • Provider awareness: Know which provider the request came from
  • Transaction tracking: Unique transaction IDs for each request

Error Handling​

  • Automatic retries: Retry failed backend requests with exponential backoff
  • Fallback responses: Return user-friendly errors on backend failures
  • Provider-specific errors: Proper error format for each provider

Architecture Overview​

Components:

  • Connectors: Parse provider-specific protocols
  • Router: Match service codes to backends
  • Session Manager: Track user sessions with TTL
  • Forwarder: Send requests to backends with retries

What You Need to Build​

To integrate with OLA Gateway, you need to build a backend application that:

  1. Exposes an HTTP endpoint (e.g., POST /ussd/callback)
  2. Accepts JSON requests from the gateway
  3. Implements your business logic (menu navigation, API calls, etc.)
  4. Returns JSON responses with menu text and session control
  5. Manages your application state (user flows, multi-step transactions)

Language agnostic: Build in any language that can handle HTTP requests (Node.js, Python, Go, Java, PHP, Ruby, etc.)

Quick Example​

Here's a minimal backend in Node.js (same concepts apply to any language):

const express = require('express');
const app = express();
app.use(express.json());

app.post('/ussd/callback', (req, res) => {
  const { msisdn, session_id, transaction_id, input } = req.body;

  // Simple menu logic
  let menu;
  if (!input) {
    menu = [
      "Welcome to MyService",
      "",
      "1. Check Balance",
      "2. Buy Airtime",
      "0. Exit"
    ];
  } else if (input === "1") {
    menu = ["Your balance is 100.00 MZN"];
  } else {
    menu = ["Invalid option"];
  }

  res.json({
    session_id,
    transaction_id,
    output: menu,
    end_session: input === "0"
  });
});

app.listen(8081);

Same concept in Python:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/ussd/callback', methods=['POST'])
def ussd_callback():
    data = request.json
    msisdn = data['msisdn']
    session_id = data['session_id']
    transaction_id = data['transaction_id']
    user_input = data['input']

    # Simple menu logic
    if not user_input:
        menu = [
            "Welcome to MyService",
            "",
            "1. Check Balance",
            "2. Buy Airtime",
            "0. Exit"
        ]
    elif user_input == "1":
        menu = ["Your balance is 100.00 MZN"]
    else:
        menu = ["Invalid option"]

    return jsonify({
        'session_id': session_id,
        'transaction_id': transaction_id,
        'output': menu,
        'end_session': user_input == "0"
    })

app.run(port=8081)

Note: These are simplified examples. Real applications should implement proper state management, error handling, and external API integration. The implementation language doesn't matter - use whatever you're most comfortable with.

Next Steps​

  1. Getting Started - Deploy the gateway and test your first integration
  2. API Reference - Complete API specification
  3. Examples - Real-world implementation examples

Use Cases​

OLA Gateway is perfect for building:

  • 📱 Mobile Banking - Balance checks, transfers, bill payments
  • ⚡ Utility Services - Electricity payments, water bills
  • 💳 Airtime & Data - Mobile top-ups and data bundles
  • 🎫 Ticketing - Event tickets, transport passes
  • 📊 Information Services - Weather, news, sports scores
  • 🏥 Healthcare - Appointment booking, test results
  • 🎓 Education - Exam results, course registration

System Requirements​

Gateway Requirements​

  • Go 1.23+ (for building from source)
  • 512MB RAM minimum (1GB+ recommended)
  • Database (SQLite for dev, PostgreSQL for production)

Your Backend Requirements​

  • Any HTTP server (Node.js, Python, Go, Java, etc.)
  • Ability to make HTTP requests (for external APIs)
  • Database for session/state management (optional but recommended)

Support​

Need help integrating with OLA Gateway?