Laravel USSD

Build production-grade USSD applications in Laravel.

laravel-ussd is a framework-agnostic USSD engine that lets you create telecom-grade USSD services with a clean, declarative API. It supports multiple gateways (Orange, Moov, Africa's Talking, Infobip, etc.) through a driver-based architecture.

Table of Contents

• Presentation
• Installation
• Configuration
• Quick Start
• Menus
• Flows
• Actions
• Sessions
• Drivers
• Simulator
• Testing
• Architecture
• Contributing
• Roadmap

Presentation

What is USSD?

USSD (Unstructured Supplementary Service Data) is a protocol used by GSM phones to communicate with service providers. It's the technology behind *123# codes — used for mobile money, balance checks, and telecom services across Africa and beyond.

What this package does

This package provides a complete framework for building USSD services:

• Menu system — Declarative, tree-based navigation
• Flow engine — Multi-step workflows with state machine
• Session management — Database, Redis, or in-memory storage
• 11 gateway drivers — Orange, Moov, Africa's Talking, Infobip, Twilio, Beem, Advanta, Hubtel, MTN, Vodacom, Airtel
• Rate limiting — Per phone number throttling with END 429 response
• Multi-language — Built-in EN/FR with easy extensibility
• Validation — Input validation per flow step
• Logging — Request/response logging
• Simulator — Web-based testing tool
• Artisan commands — ussd:list and ussd:clean
• Error handling — Graceful error recovery

Architecture overview

                    ┌──────────────────┐
                    │     Telephone    │
                    └────────┬─────────┘
                             │ USSD
                    ┌────────▼─────────┐
                    │  USSD Gateway    │
                    │(Orange, Moov, AT)│
                    └────────┬─────────┘
                             │ HTTP POST
                    ┌────────▼─────────┐
                    │  UssdController  │
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │   UssdEngine     │
                    │  (Orchestrator)  │
                    └──┬────┬────┬─────┘
                       │    │    │
              ┌────────┘    │    └────────┐
              ▼             ▼             ▼
        ┌─────────┐ ┌──────────┐ ┌──────────┐
        │ Session │ │   Menu   │ │   Flow   │
        │ Manager │ │  Manager │ │  Engine  │
        └─────────┘ └──────────┘ └──────────┘

Installation

composer require begenius/laravel-ussd

Laravel will auto-discover the service provider. If you're using Laravel < 5.5, add this to config/app.php:

'providers' => [
    BeGenius\Ussd\UssdServiceProvider::class,
],

Publish configuration

php artisan vendor:publish --tag=ussd-config

Run migrations

php artisan vendor:publish --tag=ussd-migrations
php artisan migrate

Configuration

Configure the package in config/ussd.php or via environment variables:

USSD_DRIVER=default
USSD_SESSION_DRIVER=database
USSD_SESSION_LIFETIME=2
USSD_REDIS_CONNECTION=default
USSD_ROUTES_PREFIX=ussd
USSD_SIMULATOR_ENABLED=false
USSD_LOGGING_ENABLED=true

Quick Start

1. Define menus in a Service Provider

<?php

namespace App\Providers;

use BeGenius\Ussd\Facades\Ussd;
use Illuminate\Support\ServiceProvider;

class UssdServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Ussd::menu('welcome')
            ->title("Welcome to MyService")
            ->option('1', 'Check Balance')
            ->option('2', 'Transfer Money')
            ->option('3', 'Help', nextMenu: 'help');
    }
}

2. Configure your gateway

Set your USSD gateway to send POST requests to:

https://your-domain.com/ussd/callback

3. The gateway sends payloads like

{
    "sessionId": "ABC123",
    "phoneNumber": "22670000000",
    "network": "ORANGE",
    "text": "1"
}

Your application handles the rest.

Menus

Menus are the building blocks of your USSD application. They display options and handle navigation.

API

use BeGenius\Ussd\Facades\Ussd;

Ussd::menu('main')
    ->title("Main Menu")
    ->option('1', 'Balance', BalanceAction::class)
    ->option('2', 'Transfer', TransferFlow::class)
    ->option('3', 'Settings', nextMenu: 'settings')
    ->option('0', 'Exit');

Sub-menus

Ussd::menu('settings')
    ->title("Settings")
    ->option('1', 'Language', LanguageAction::class)
    ->option('0', 'Back', nextMenu: 'main');

Navigation flow

• Action: An action class (invokable) executes business logic
• Flow: A multi-step workflow
• nextMenu: Navigate to another menu
• No action/no nextMenu: Re-renders the current menu

Rendering

Menus are auto-rendered as CON responses with numbered options:

CON Main Menu
1. Balance
2. Transfer
3. Settings
0. Exit

Flows

Flows handle multi-step transactions like money transfers.

Creating a Flow

namespace App\Ussd\Flows;

use BeGenius\Ussd\Core\UssdContext;
use BeGenius\Ussd\Flows\Flow;
use BeGenius\Ussd\Flows\Step;
use BeGenius\Ussd\Flows\StepResult;
use BeGenius\Ussd\Responses\UssdResponse;

class TransferFlow extends Flow
{
    public function __construct()
    {
        parent::__construct('transfer', 'ask_recipient');

        $this->addStep(new class extends Step {
            public function name(): string
            {
                return 'ask_recipient';
            }

            public function handle(UssdContext $context): StepResult
            {
                return StepResult::next(
                    'ask_amount',
                    UssdResponse::continue('Enter recipient phone:')
                );
            }
        });

        $this->addStep(new class extends Step {
            public function name(): string
            {
                return 'ask_amount';
            }

            public function validate(UssdContext $context): ?string
            {
                $amount = $context->input();
                if (!is_numeric($amount) || $amount <= 0) {
                    return 'Invalid amount. Enter a positive number.';
                }
                return null;
            }

            public function handle(UssdContext $context): StepResult
            {
                $context->session()->set('amount', $context->input());

                return StepResult::next(
                    'confirm',
                    UssdResponse::continue(
                        "Confirm transfer:\n".
                        "To: {$context->session()->get('recipient')}\n".
                        "Amount: {$context->input()} FCFA\n".
                        "1. Confirm\n".
                        "2. Cancel"
                    )
                );
            }
        });

        $this->addStep(new class extends Step {
            public function name(): string
            {
                return 'confirm';
            }

            public function handle(UssdContext $context): StepResult
            {
                if ($context->input() === '1') {
                    // Process the transfer...
                    return StepResult::complete(
                        UssdResponse::end('Transfer successful!')
                    );
                }

                return StepResult::complete(
                    UssdResponse::end('Transfer cancelled.')
                );
            }
        });
    }
}

Register a flow in a menu

Ussd::menu('main')
    ->option('2', 'Transfer Money', TransferFlow::class);

Or register it independently:

$flow = new TransferFlow();
Ussd::registerFlow($flow);

Actions

Actions are invokable classes that handle a single menu selection.

namespace App\Ussd\Actions;

use BeGenius\Ussd\Core\UssdContext;
use BeGenius\Ussd\Responses\UssdResponse;

class BalanceAction
{
    public function __invoke(UssdContext $context): UssdResponse
    {
        $balance = $this->getBalance($context->session()->phoneNumber());

        return UssdResponse::end("Your balance is: {$balance} FCFA");
    }

    private function getBalance(string $phoneNumber): float
    {
        // Query your database or API
        return 15000.00;
    }
}

You can also use closures:

Ussd::menu('main')
    ->option('1', 'Balance', function (UssdContext $context) {
        return UssdResponse::end('Your balance is 5000 FCFA');
    });

Sessions

Sessions persist user state across USSD requests. The package supports three drivers.

Session data

Store temporary data during flows:

$context->session()->set('recipient', '22671234567');
$context->session()->set('amount', '5000');

$recipient = $context->session()->get('recipient');
$hasAmount  = $context->session()->has('amount');
$context->session()->forget('amount');

Session lifecycle

1. Created — When a user dials the service code
2. Active — During menu navigation and flow execution
3. Expired — After session_lifetime minutes of inactivity
4. Destroyed — After successful END response

Drivers

USSD Gateway Drivers

Built-in gateway drivers

Set the driver in .env:

USSD_DRIVER=orange

Custom gateway driver

Create a driver for your specific gateway:

namespace App\Ussd\Drivers;

use BeGenius\Ussd\Contracts\UssdDriver;
use BeGenius\Ussd\Http\Requests\UssdRequest;
use Illuminate\Http\Request;

class OrangeDriver implements UssdDriver
{
    public function parseRequest(Request $request): UssdRequest
    {
        return new UssdRequest(
            sessionId:   $request->input('sessionId'),
            phoneNumber: $request->input('msisdn'),
            network:     'ORANGE',
            text:        $request->input('ussdText', ''),
            raw:         $request->all(),
            serviceCode: $request->input('serviceCode'),
        );
    }
}

Register your driver in the service provider:

// In UssdServiceProvider registration
$this->app->bind(UssdDriverContract::class, function ($app) {
    return new OrangeDriver();
});

Session Drivers

Built-in session drivers:

Switch driver via .env:

USSD_SESSION_DRIVER=redis
USSD_REDIS_CONNECTION=default

The Redis driver stores sessions as JSON with a configurable TTL (session_lifetime) and supports custom Redis connections.

Simulator

Test your USSD application without a real gateway:

USSD_SIMULATOR_ENABLED=true

Open http://localhost:8000/ussd/simulator in your browser.

┌─────────────────────┐
│   USSD Simulator    │
│                     │
│  CON Welcome        │
│  1. Balance         │
│  2. Transfer        │
│                     │
├─────────────────────┤
│ [Input: 1     ] [→] │
│                     │
│ Session: abc123     │
└─────────────────────┘

⚠️ Disable in production: USSD_SIMULATOR_ENABLED=false

Artisan Commands

ussd:list

List all registered menus and their options:

php artisan ussd:list

Output:

+----------------+---------+-----------------------+
| Menu           | Options | Preview               |
+----------------+---------+-----------------------+
| welcome        | 3       |  1. Check Balance     |
|                |         |  2. Transfer Money    |
|                |         |  3. Help              |
+----------------+---------+-----------------------+

ussd:clean

Purge expired sessions from storage:

php artisan ussd:clean                    # purge sessions > 2 min old
php artisan ussd:clean --minutes=5        # purge sessions > 5 min old

Rate Limiting

Protect your USSD endpoint from abuse. The built-in ThrottleUssdRequests middleware limits by phone number (with IP fallback):

// In a route file
Route::post('/ussd/callback', [UssdController::class, 'handle'])
    ->middleware('throttle:ussd');

Customize limits in AppServiceProvider:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('ussd', function ($job) {
    return Limit::perMinute(10)->by($job->input('phoneNumber', $job->ip()));
});

When the limit is exceeded, the middleware returns a 429 Too Many Requests response with END format.

Multi-language

Built-in translations for English and French.

__('ussd::ussd.session_expired');
// en: "Session expired. Please dial again."
// fr: "Session expirée. Veuillez recomposer le code."

Switch locale as usual:

app()->setLocale('fr');

Publish and customise:

php artisan vendor:publish --tag=ussd-lang

Available keys:

Testing

composer test

The package uses PHPUnit with Orchestra Testbench.

public function it_creates_a_continue_response(): void
{
    $response = UssdResponse::continue("Welcome\n1. Balance");

    $this->assertTrue($response->isContinue());
    $this->assertEquals('CON', $response->type());
    $this->assertEquals("CON Welcome\n1. Balance\n", $response->toString());
}

Architecture

src/
├── UssdServiceProvider.php        # Laravel service provider
├── Facades/
│   └── Ussd.php                   # Facade for UssdEngine
├── Config/
│   └── ussd.php                   # Configuration file
├── Core/
│   ├── UssdEngine.php             # Main orchestrator
│   ├── UssdSession.php            # Session value object
│   └── UssdContext.php            # Request context
├── Http/
│   ├── Controllers/
│   │   ├── UssdController.php     # Gateway callback controller
│   │   └── SimulatorController.php # Web simulator
│   ├── Middleware/
│   │   └── ThrottleUssdRequests.php # Rate limiter middleware
│   └── Requests/
│       └── UssdRequest.php        # Parsed USSD request
├── Responses/
│   └── UssdResponse.php           # CON/END response builder
├── Menus/
│   ├── Menu.php                   # Menu definition
│   └── MenuOption.php             # Single menu option
├── Flows/
│   ├── Flow.php                   # Multi-step workflow
│   ├── Step.php                   # Single flow step
│   └── StepResult.php             # Step execution result
├── Contracts/
│   ├── UssdDriver.php             # Gateway driver interface
│   └── SessionDriver.php          # Session storage interface
├── Drivers/
│   ├── Gateway/                   # 11 gateway driver files
│   └── Session/
│       ├── DatabaseSessionDriver.php # DB session storage
│       ├── RedisSessionDriver.php    # Redis session storage
│       └── ArraySessionDriver.php    # In-memory session
├── Services/
│   ├── SessionManager.php         # Session lifecycle
│   └── MenuManager.php            # Menu registry
├── Exceptions/
│   ├── UssdException.php          # Base exception
│   ├── InvalidMenuException.php   # Menu not found
│   └── SessionExpiredException.php # Session timeout
└── Console/
    ├── Commands/
    │   ├── UssdListCommand.php     # ussd:list
    │   └── UssdCleanCommand.php    # ussd:clean
    └── Resources/
        └── lang/                   # Translation files (EN/FR)

Key design patterns

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -am 'Add my feature'
4. Push: git push origin feature/my-feature
5. Open a Pull Request

Please follow PSR-12 coding standards and include tests.

Roadmap

v1.0

• Menu system with fluent API
• Multi-step flow engine (state machine)
• Session management (database + Redis + array)
• 11 gateway drivers (Orange, Moov, AT, Infobip, Twilio, Beem, Advanta, Hubtel, MTN, Vodacom, Airtel)
• Rate limiting per phone number
• Multi-language support (EN/FR)
• Artisan commands (ussd:list, ussd:clean)
• CSRF exclusion auto-configuration
• USSD simulator
• Request/response logging
• Error handling
• PHPUnit test suite
• GitHub Actions CI

v1.1

• Visual flow designer UI
• Analytics dashboard
• Webhook integration
• REST API for session management
• Broadcast messages
• Push USSD (MT sessions)

v2.0

• Visual flow designer UI
• Webhook integration
• REST API for session management
• Push USSD (MT sessions)
• Laravel Livewire component

License

laravel-ussd is open-source software licensed under the MIT license.

Built with ❤️ by BeGenius