Mobius USSD Gateway Menues Configuration Example

Post action notification

Post action notification may be effective to advertise or notify user after some operation. For example on call being disconnected mobile network may notify USSD gateway and initiate new push USSD dialog towards the customer. As result user would see information while he is still interacting with his mobile phone.

Example : Personal balance notification.

In order to complete this logic the USSD gateway should have information of customer name , service , and balance In order to simplify the process we would keep all external variables as part of initial API call to USSD gateway and all of them would be under root element custom inside JSON

In order to configure the menu that would handle such scenario lets get into USSD UI and press on USSD Shortcodes option. Press on Add New Row Button. In type lets select NETWORK_INITIATED , select the Destinations for which this menu should be supported and enter the menu name , for example Balance Notification. After the menu is being created lets press on menu option near it and Builder. This will open us empty menu builder screen with single block available - Welcome.

First we need to define the variables that we would be using for this scenario. In order to do some lets press on menu option inside welcome block and press on edit. Inside the dialog lets press on add new field , in path enter custom.customerName , variable - customerName and default value lets keep empty.

Then this procedure should be repeated 2 more times with following data : path - custom.service, variable - service and path - custom.balance and variable - balance. What we just configured is mapping from incoming message format ( in our article it would be JSON but it may also be XML or urlencoded form ) to system variables that may be used at any stage during the call. After entering all the variables lets press on save.

Please note that nothing is saved on server till Save Menu is being called. Now lets configure notification. For that we should press on + option in block right to welcome and select message option. In new dialog lets enter the following message Dear {customerName} your balance for {service} is {balance} and press on save button. When done , lets press on Save Menu button to save all our work.And we are done.

In order to send the API request lets initiate push request to http://127.0.0.1:28080/ussdcalls/push ( the protocol , ip and port are depending on your server/s configuration )
The Content-Type should be application/json And the following request should be sent ( first login api should be called and then proper username and sessionID should be used, please read common API for more details )
{
   "data":
   {
      "alertPattern": 10,
      "destinationID": "6310785f20b51e7069c9bbe2",
      "menuID": "63108fa49f9623126f7f7721",
      "msisdn": "8801500121121",
      "request": "63108f25dab78794a49f9623",
      "custom":
      {
         "customerName":"Abby Enrique",
         "service":"voice",
         "balance":12.15
      }
   },
   "sessionID": "62c173c572d57e70dd99f190",
   "username": "admin"
}

You should receive the USSD push with message Dear Abby Enrique your balance for voice is 12.15

Menu based selection of package

Lets assume we would like to allow our customer selecting the roaming package through USSD short *123#
We may allow data only packages , and mixed packages, for data lets assume we have 3 packages -
1GB for 1 week for 10$,
2GB for 2 weeks for 20$, and
4GB for 4 weeks for 30$.

For mixed packages lets assume we have
500MB+10 SMS+10Min Voice for 10$ and
1GB+50SMS+50Min Voice for 20$.

In order to configure the menu that would handle such scenario lets get into USSD UI and press on USSD Shortcodes option. Press on Add New Row Button. In type lets select MS_INITIATED , select the Destinations for which this menu should be supported and enter the menu name , for example Balance Roaming. In shortcode lets enter *123# and press on save.

After the menu is being created lets press on menu option near it and Builder. This will open us empty menu builder screen with single block available - Welcome. Lets press on plus sign to create new block and select Menu option.Invalid Option message would be present when user enter option that is not allowed, lets write there "Option is not valid , please try again". In message lets enter :
1 for data only
2 for data+SMS+voice
Inside menu options lets enter 1 ( and press on enter ) and 2 ( and press on enter ). Press on save button

2 new + signs appears after the menu. Lets press on + near 1 and select menu again. In Invalid option lets enter "Option is not valid , please try again". In message:
1 for 1GB for 1 week for 10$
2 for 2GB for 2 weeks for 20$
3 for 4GB for 4 weeks for 30$
Inside menu options lets enter 1 ( and press on enter ), 2 ( and press on enter ) and 3 ( and press on enter ). Press on save button

Lets press on + near 2(after first menu from left) and select menu again. In Invalid option lets enter "Option is not valid , please try again". In message:
1 for 500MB+10 SMS+10Min Voice for 10$
2 for 1GB+50SMS+50Min Voice for 20$
Inside menu options lets enter 1 ( and press on enter ) and 2 ( and press on enter ). Press on save button

After processing those 2 stages we have collected all the required details and know what is the package that customer has ordered. However USSD Gateway itself is not responsible for enabling any service. Therefore it would be required to send this details to external server that will process the data and will enable the package. To do so in all 5 + active on the right we need to press on + and select external service. In request URL lets enter http address on which external server would be accepting the notifications. Request format may be JSON, XML or ENCODED FORM. Depending on selection the USSD Gateway will format the message accordingly. Response from server may be coming in any of three formats , USSD gateway supports all of them automatically. For more details please check USSD API documentation / External block , which has examples of all formats definition.
While Request TAB is active lets press on add new field. This is required in order to add proper service ID to the request. In path lets enter serviceID ( according to this value the value would be positioned in the sent message ), in variable lets also enter serviceID ( in case variable was defined in previous stage then the value would be taken from this variable , otherwise it would be taking the default value defined ). For default value lets define 1 ( we will repeat same procedure with values 1-5 for all options ).
Now lets switch to response TAB.Lets press on Add new field there. We would expect that remote server would either confirm or reject us succesfull package order. In case order is not succesfull it would provide detailed message to us. We will add 2 variables, one success , with path result.success and default value 0, and second errormessage, with path result.errormessage and without default value ( we expect the response to have element result in it, and result should have 2 child elements -> success and errormessage ).

After entering all the properties , lets press on save button. This operation should be repeated for all 5 available block ( with plus ). Now we need to add handling of the responses from server.To do so , lets press on + on first available option and select variable menu.
In variable name lets enter success , because this is the variabled based on which we will do our decision. In menu options lets enter 0 ( and press on enter ) and 1 and press on save.All other external services calls should do exactly the same. Therefore we would press on plus near each of it , select go to option and inside of it select Variable:success option.

We have 2 unhandled leafs left - 0 and 1 after the variable menu handling. 1 means success therefore lets press on + for it and select Message. Inside the message lets enter "You package has been ordered" and press on save.

Lets press on + near 0 , and select also the Message. Inside the message lets enter An error occured while ordering package.{errormessage} and press on save button. {variable_name} would be automatically replaced by variable value collected during the call. In this case it would be the error message sent from external service. When we completed lets not forget to press on save button

Autocomplete with menu based

In some cases its required to have not only shortcode but allow user selecting specific option in one operation. This is usefull to save customer time and improve handling. Lets take as example the previous Roaming menu. Generally we have following pathes in it:
*123#11 - For data only 1GB for 1 week for 10$
*123#12 - For data only 2GB for 2 weeks for 20$
*123#13 - For data only 4GB for 4 weeks for 30$
*123#21 - For data+SMS+voice 500MB+10 SMS+10Min Voice for 10$
*123#22 - For data+SMS+voice 1GB+50SMS+50Min Voice for 20$

When we create or edit the shortcode we have an option called - Extendable. If we will enable this option the user would be able to enter *123#, *123#1 , *123#2 and all 5 options above and all would be handled by same menu.

If user will enter part of the full string as first stage he will get into first or second level menu. If he will enter the full string then he will get response message right after first request. Depending on you scenarios you may enable or disable this option.

Variables based menu explained

Based on previous but replacing with input Roaming menu may be handled in different way. Each menu may be replaced by collect option. In case different options requires different handling after collect variable based menu may be added. In order to configure the menu that would handle such scenario lets get into USSD UI and press on USSD Shortcodes option. Press on Add New Row Button. In type lets select MS_INITIATED , select the Destinations for which this menu should be supported and enter the menu name , for example Balance Roaming. In shortcode lets enter *123# and press on save.

After the menu is being created lets press on menu option near it and Builder. This will open us empty menu builder screen with single block available - Welcome.

Lets press on plus button and select collect option. In message lets enter :
1 for data only
2 for data+SMS+voice
In variable name lets enter servicetype and press on save.

Now lets press on new plus button and select variable menu In Invalid Option Message lets enter: Option is not valid , please try again; in variable name servicetype, and in menu options lets add 1 and 2.

Lets press on + near 1 and select collect option again In variable name lets enter subtype, In message lets enter:
1 for 1GB for 1 week for 10$
2 for 2GB for 2 weeks for 20$
3 for 4GB for 4 weeks for 30$

Same we can do with second option , but the message would be
1 for 500MB+10 SMS+10Min Voice for 10$
2 for 1GB+50SMS+50Min Voice for 20$

As final stage lets configure external service call ( press on top plus ).This time we will pass 2 variables : servicetype and subtype in request. The remaing configuration may be done in same way as it was done on original Roaming menu.

We also dont need to configure external service twice. We may do it once and second leaf may be connect by using go to and selecting external service call. The advantage of this approach is that we have much less configuration to be done. The main disadvantage is that its not possible to use autocomplete feature with collect because the collect may be accepting more then one character for each stage Its up to each USSD deployment how and which way to use

Proxy call explained

In general means that every request that is received from MS network would be forwarded to external service. External service should response to the received message and then send new request to allow notification to end user or request another input. So generally saying the proxy is usefull when the USSD should not handle any call logic , but only forward the messages from one leg to another. More details regarding proxy messages format can be found in API documentation.

The proxy call may be either initiated by MS or initiated by Network. In second case first push API should be called to establish new call. Hopefully this short demo describes all the features and options allowed by USSD gateway and provide the better view on how to proper configure the call logic.