Aguva Ussd is a modern and adaptable USSD application solution that accommodates various languages, such as English and Swahili, with the option to integrate additional languages as needed. Its syntax is clear and sophisticated, ensuring exceptional user-friendliness. Additionally, it includes a built-in USSD simulator, streamlining the debugging and upkeep of the application.
composer require aguva/ussd:dev-main
php artisan vendor:publish --provider="Aguva\Ussd\Providers\UssdServiceProvider" --tag=aguva-ussd-lang --force
php artisan migrate
DEFAULT_MESSAGE= # The default message to show when no other message is available
RESTRICT_TO_WHITELIST=true # Set to false to allow all msisdns
LOG_USSD_REQUEST=true # Set to true to log all ussd request payloads from provider
WHITELIST_MSISDNS="254705799644" # Comma separated list of msisdns to whitelist
END_SESSION_SLEEP_SECONDS=2 # Delay in seconds before ending session
USSD_CODE=657 # This is the ussd code given to you by your provider eg 999
ONLINE_ENDPOINT='api/process-payload/55034fd5-bd23h5d9948f' # The endpoint to receive ussd payloads from provider
Create a UssdProcessor.php file in root project's app/Repositories dir & add the following boilerplate code. This is your PLAYGROUND, GO CRAZY
N/B Treat each a method as a new USSD screen instance
<?php
namespace App\Repositories;
use Aguva\Ussd\Repositories\Handler;
class UssdProcessor
{
// Distinguish if it's a new user (first dial) or a registered user
static function activityHome(Handler $handler, $params)
{
if (array_key_exists('newUser', $handler->userInput) && $handler->userInput['newUser']) {
return self::activityHomeNewUser($handler, $params);
}
return self::activityHomeExistingUser($handler, $params);
}
// This is an existing user
static function activityHomeExistingUser(Handler $handler, $params)
{
$handler->message = __('ussd.welcome_new_user', ['name' => $handler->user->first_name]);
$menu = [
1 => [
'text' => __('ussd.item_home'),
'activity' => 'activityHome',
],
2 => [
'text' => __('ussd.item_choose_language'),
'activity' => 'activityChooseLanguage',
],
3 => [
'text' => __('ussd.item_quit'),
'activity' => 'activityQuit',
]
];
$handler->menuItems = $menu;
return self::activityReturnValidMessage($handler);
}
// This is a new user
static function activityHomeNewUser(Handler $handler, $params)
{
$handler->message = __('ussd.welcome_registered_user', ['name' => '']);
$menu = [
1 => [
'text' => __('ussd.item_choose_language'),
'activity' => 'activityChooseLanguage',
],
2 => [
'text' => __('ussd.item_quit'),
'activity' => 'activityQuit',
]
];
$handler->menuItems = $menu;
return self::activityReturnValidMessage($handler);
}
// Exit the application
static function activityQuit(Handler $handler, $params)
{
$handler->message = __('ussd.item_message_quit');
$handler->end = true;
return self::activityReturnValidMessage($handler);
}
// Choose app language
public static function activityChooseLanguage(Handler $handler, $params)
{
$handler->message = __('ussd.item_choose_language');
$languageLookUp = ['1' => 'en', '2' => 'sw'];
$handler->userInput['localeLookup'] = $languageLookUp;
$handler->menuItems = [
'1' => [
'text' => __('ussd.item_language_english'),
'activity' => 'activityChangeLanguage'
],
'2' => [
'text' => __('ussd.item_language_swahili'),
'activity' => 'activityChangeLanguage'
],
'0' => [
'text' => __('ussd.item_navigation_home'),
'activity' => 'activityHome'
]
];
return self::activityReturnValidMessage($handler);
}
// Change the app language
public static function activityChangeLanguage(Handler $handler, $params)
{
if (!collect($handler->userInput['localeLookup'])->has($handler->ussdString)) {
return self::activityHome($handler, $params);
}
$locale = $handler->userInput['localeLookup'][$handler->ussdString];
$handler->user->locale = $locale;
$handler->user->save();
$handler->setLang();
$handler->message = __('ussd.item_locale_saved');
$handler->menuItems = [
'0' => [
'text' => __('ussd.item_navigation_home'),
'activity' => 'activityHome'
]
];
return self::activityReturnValidMessage($handler);
}
// Returned message
public static function activityReturnValidMessage(Handler $handler)
{
if ($handler->invalidInput) {
$handler->message = __('ussd.enter_valid_input') . " $handler->ussdString\n$handler->message";
}
return $handler;
}
/**
* ALL YOUR OTHER MENUS WILL BE WRITTEN HERE... FEEL FREE TO PLAY AROUND
*/
}The ussd simulator can be found in the url "/simulator". Kindly note that it mimics a live ussd environment meaning that you have to click "new session" button whenever you want to simulate the start of a new session.
Make sure you listen to the following queue(s) which is used to save ussd sessions data into the database
save-ussd-message
You could use either of the following;
N/B Install horizon console or beanstalkd console to help you monitor the queues & also install the necessary respective laravel packages.
composer remove aguva/ussd
If you discover a security vulnerability within the library, please send an e-mail to Cyril Aguvasu. All security vulnerabilities will be promptly addressed.
This library is owned and maintained by Cyril Aguvasu