Mobiverse USSD plugin for Laravel

About

This is a package to help you integrate the Mobiverse USSD service into your Laravel application. Users will be able to access your application on USSD with codes like *1234# from their phones.

This package uses code from https://github.com/jowusu837/hubtel-ussd-plugin-laravel created by Victor James Owusu.

Installation

Require the gashey/laravel-mobiverse-ussd package in your composer.json and update your dependencies:

$ composer require gashey/laravel-mobiverse-ussd

Add the LaravelMobiverseUssd\UssdServiceProvider to your providers array:

Gashey\LaravelMobiverseUssd\ServiceProvider::class,

Usage

Your application should now have an endpoint for USSD access. You can use the Mobiverse USSD Simulator to test your application. Supply your application url as: http://your-application.com/ussd

Customization

A simple USSD flow comes with this plugin so you can immediately test to see if your setup is working. You can create custom USSD flows by creating Activities. Start by creating a new folder in your app directory called USSD. This is where you will store all your USSD related logic.

A USSD activity is just a php class that extends the UssdActivity class. An example of an activity class is below:

namespace App\Ussd\Activities;

use App\Ussd\Activities\MenuSelection;
use Gashey\LaravelMobiverseUssd\Lib\UssdActivity;
use Gashey\LaravelMobiverseUssd\Lib\UssdResponse;

class HomeActivity extends UssdActivity
{
    public function run() {
        $this->response->Type = UssdResponse::RELEASE;
        $this->response->Message = 'Ussd is working!';
        return $this;
    }
    
    public function next() {
        return MenuSelection::class;
    }

}

An activity class must implement 2 methods: run() and next().

The run() method is the main entry point for the activity and must always return $this.

The next() must return a reference to the next activity to be executed. You can do this by simply returning a string with the full namespace of the next activity class or you can use the ::class approach to have php resolve it for you.

You have access to the current request $this->request, the response to be sent $this->response, and the current USSD session $this->session from within the activity.

The request and response properties exposes all the properties of a USSD request and response respectively.

The session property is an array. Note that the session is implemented on top of your existing Laravel cache. It allows you to persist state throughout your USSD session. You can store a value in the session like so: $this->session['name'] = 'Jane Deer', and retrieve it elsewhere like so: $name = $this->session['name'].

Once you have created your activiy files, you need to set your entry point activity in the config file as shown in the next section.

Configuration

The defaults are set in config/ussd.php. Publish the config using this command:

$ php artisan vendor:publish --provider="Gashey\LaravelMobiverseUssd\UssdServiceProvider"

return [
    "home" => \App\Ussd\Activities\HomeActivity::class
];

License

Released under the MIT License, see LICENSE.