Installation - Laravel USSD Documentation

Install via Composer

You can install the package via composer:

composer require catalysteria/laravel-ussd

Publish Configuration

Laravel USSD provides zero configuration out of the box. To publish the config, run the vendor publish command:

php artisan vendor:publish --provider="Vendor\LaravelUssd\Providers\LaravelUssdServiceProvider"

This will publish the configuration file to config/ussd.php.

Configuration File

This is the default content of the config file:

                
                    return [
    'initial_state' => 'App\\Ussd\\States\\WelcomeState',

    'state_namespace' => 'App\\Ussd\\States',

    'action_namespace' => 'App\\Ussd\\Actions',

    'cache_store' => env('USSD_CACHE_STORE', null),

    'default_response_suffix' => '',

    'error_state' => null,

    'max_retries' => 3,

    'continuity' => [
        'enabled' => true,
        'timeout' => 900,
        'resume_prompt' => 'We noticed you have an unfinished session. Choose an option:',
        'resume_option_key' => '1',
        'resume_option_text' => 'Resume previous session',
        'restart_option_key' => '2',
        'restart_option_text' => 'Start over',
    ],
];

Understanding the Configuration

By default, new state classes will be created in app/Ussd/States directory with App\Ussd\States namespace. That can be changed with the state_namespace variable in config/ussd.php.

Also, a new action with App\Ussd\Actions namespace by default. You can change it just like the states.

The cache_store variable specifies which particular store to use. The list can be found in config/cache.php under the stores array variable. Leave it at null to use your default cache-store.

Register the USSD Route

Register the USSD route in routes/api.php:

Route::post('/ussd', \Vendor\LaravelUssd\Http\Controllers\UssdController::class)
    ->middleware('ussd.normalize');

Create Your First State

Scaffold your first state:

php artisan ussd:state WelcomeState

Set the Initial State

The initial state is the first state that users see when they dial your USSD code. Configure it in config/ussd.php:

return [
    'initial_state' => 'App\\Ussd\\States\\WelcomeState',
    
    // ... other configuration
];

Make sure the class name matches the state you created. The initial state must be a fully qualified class name (including namespace). This is the entry point for all new USSD sessions.