USSD API class

USSD API wrapper class

This class completely implemets all the interaction logic to Yate USSD gateway. Support for sync&async modes and session data storage. Requires proper USSD gateway configuration. See Yate docs for details.

Methods

__construct($uri, Log\LoggerInterface $logger = null)

URI for USSD GW to send async call and PSR-3 compatible logging object, no logging if null.

processCallback()

Do all the job to process GET request from the gateway, retreive session data and setup the class instance with callback data.

sessionStart($msisdn, $message, array $sessionVars = null)

Starts the new network-initiatend session to $msisdn with $message. Allocates sesson ID, also may save array of session vars to session data and then it be restored on callback after user answer. May be called just after constructor.

function sessionAnswer($message)

Only be called after sucessful processCallback(). Answer to the user in the current session and instruct GW to ask for user input.

sessionStop($text = null)

Only be called after sucessful processCallback(). Finalises the session with messsage to the user which may only be dismissed. If no text suppled, standard message USSD session finished be sent.

notify($msisdn, $message)

Sends flash USSD notification be only dismissed, no session. May be sent just after constructor.

inSession()

Returns true if callback was processed and session state detected.

getSessionVars()

Returns current array of [session-persistent variables|session-data-storage]. It will be sent for storage to USSD gateway and retreived on the next callback.

getVars()

Returns all the variables, supplied by GW with it's GET call. Depends of what you have configured on GW.

getSessionState()

Returns session state afeter successfull callback processing:

• start - it is the first message in mobile-originated session
• `progress' - it is some in-session message, session is active
• stop - session was terminated by user or by error, no future messages from App accepted. Some extra info may be found in the text field

setSessionVars(array $sessionVars)

Completely rewrites session-persistent stored vars.

addSessionVar($name, $value)

Add session-persistent variable to array. Rewrites if already exists.

delSessionVar($name)

Removes session-persistent variable. No effect and no error if not exists.

Usage

Preparing USSD GW

USSD gateway must be properly configured to send callback to the endpoint where you catch it. The callback template recommnded to be as follows:

http(s)://{your app uri}?id=${id}&msisdn=${msisdn}&text=${text}&operation=${operation}&sync=${sync}&seq=${seq}&code=${code}&user=${user}&hlr=${hlr}&scf=${scf}&menu_path=${menu_path}&sessiondata=${sessiondata}

Absolutely required: id,msisdn,text,operation,sync. Parameter sessiondata is required to store USSD application session data on the Yate USSD GW side, so applicatein may be almost stateless.

Some hints and extra information for correct setup:

1. USSD Codes section only works for MO-initiated USSD session and keep track of the session, so it passed to the same handler all the time.
2. Everythig has no match at USSD codes secton will be sent to uri/template configured at USSD GW section. Also, any network-oriented session will send all user answers there. No way to route it any other handler.
3. Use of sync mode is higly discouraged! There no way to control gateway behaviour and it may ask for user input or just send message with dismiss button on it own descretion. The wrapper placing operation hint to answer headers as defined in the docs, but it does not work. Use async mode, it is determnistic.

Application setup

Setup web server with PHP support. Create an endpont where USSD GW will send GET requests. Create your appplication.

Application, opton1: Extend USSD class with your application logic

See USSDTestApp class as an exaple. Create a script to handle requests with your class, as example:

<?php

require '../../vendor/autoload.php';

use YateAPI\USSDTestApp;

$u = new USSDTestApp('http://{host:port}/usgw/ussd.php', '/var/log/ussdtest.log');

$u->run();

That's all!

Application, opton 2: Use USSD class to handle interacton

In a script invoked by USSD GW call, do:

1. Create USSD class instance with proper uri and logger
2. Call ->processCallback() to setup all the context
3. Get the callback data by ->getVars() and session-persistent data with ->getSessionVars()
4. Do all the application logic, do not forget to update session-persistent data within the class instance.
5. Call ->sessionAnswer($message) to ask user for some input or `->sessionStop($mwssage) for final message.

That's all!

Network-initiated session

To initiate session from network:

1. Create USSD class instance with proper URI and logger
2. Use ->SessionStart() method to send the first $message to $msisdn. User answer will be sent in the callback.

Pease, mind that all the user answers of network-initiated session be sent to the main calback point under USSD GW config section

<?php

require '../../vendor/autoload.php';

use YateAPI\USSDTestApp;

$u = new USSD('http(s)://{host:port}/usgw/ussd.php');

echo ($u->sessionStart('{msisdn}', 'This session started from network, your input?') ? 'success' : 'failure') . PHP_EOL;

USSD Flash notification

To send flash notification:

1. Create USSD class instance with proper URI and logger
2. Use ->notify() method to send flash $message to $msisdn

<?php

require '../../vendor/autoload.php';

use YateAPI\USSD;

$u = new USSD('http(s)://{host:port}/usgw/ussd.php');

echo ($u->notify('{msisdn}', 'This is flash USSD message') ? 'success' : 'failure') . PHP_EOL;