Getting started with USSD
Panacea Mobile has developed a USSD gateway service that is simple enough to be used by someone with no technical experience, while also being extremely flexible for users with the necessary skills to create advanced applications.
USSD Strings
A string is what the user enters on their mobile device, for example *120*912# . When creating a USSD campaign from your Panacea Mobile Account Dashboard you will be able to select what USSD string you would like to use. Your account will also have a free sub-string such as ‘*120*912*xxx# that you can use to prototype your USSD campaign or service. The free sub-string has 500 free sessions per month that can be used, after which normal standard rate session fees apply.
USSD Campaigns
In order to use Panacea Mobile’s USSD service you must create a campaign. A campaign allows you to build your application (or multiple applications as different campaigns). Once a campaign is created, you will be able assign your USSD String to your campaign. As part of your campaign you will need to select a Start Node (the first node the user hits when they enter the string). Campaigns allow you to report specifically on a particular usage once users have interacted with the system.
USSD Nodes
Nodes are essentially the ‘pages’ of your USSD application, they control what the user sees, and where they go in the process. As above, when the user starts the session they will go to the Start Node as selected by the campaign setup.
Nodes contain the following set of variables:
| Variable | Type | Description |
|---|---|---|
| Name | Text | The name of the node is largely for presentation purposes (so you can more easily navigate your nodes) it does however get stored in your session data when users reply to the content. If for example your node name was ‘User Gender’ which asked the user to enter their gender this would be stored in a variable ‘User_Gender’ (spaces removed) which could be used later to check conditions against and would also be passed on to any HTTP URL as well as stored with the session transcript. |
| Response | (Text / URL) | This is the text that the user first sees when entering the node. If the ‘Text from URL’ is selected, the Panacea Mobile system will retrieve the URL and respond back to the user with the text output by this URL. |
| Error | (Text / URL) | This is exactly the same as the Response Text/URL, however this will only be displayed if the user responded to the question posed on this node, but the response did not match any response conditions (could not be redirected to the next/new node) |
| Response conditions | N/A | Response conditions are how users are moved between nodes. Response conditions get executed when the user responds to the Response Text. If a response condition is matched, the user will then be diverted to the next node as selected. If no-valid responses were found, the error text/URL will be displayed. |
| Actions | N/A | Actions are set of things to do when a user enters a node. These can be calling HTTP URLs, Adding phone numbers to lists, sending emails, sending SMS, and so forth. These actions are executed every time the node is processed, whether the user is entering for the first time, whether they have been diverted back through the session or even if they responded erroneously to the same node. |
| Last node | Ends session | This yes/no option, if set will close the USSD session with the user, not allowing them to respond. No response conditions will be processed (because there will be no response). |
Example campaign setup
To simplify the above, we have created a sample data set to explain what would take place.
- Panacea Mobile has assigned a new string to our service *100*123#
- We have created a new campaign ‘Customer Survey’, and set the initial node to ‘Terms and Conditions’.
Node name: Terms and Conditions
Response type set to ‘text’.
Response text set to:
‘Thank you for participating in our survey, please reply with 1 to confirm you accept our terms and conditions or enter 0 to decline.’
Error text set to:
‘Please enter a valid response. Thank you for participating in our survey, please reply with 1 to confirm you accept our terms and conditions or enter 0 to decline’
Response conditions:
If response 1 – go to node: “Location Check”
If response 0 – go to node: “Terms Declined”
Last node/end session set to no.
Node name: “Terms declined”
Response type set to ‘text’.
Response text set to:
‘Thank you, you have opted out of our survey’.
Last node/end session set to yes.
No error text or response conditions are set (irrelevant).
Node name: “Location Check”
Response type set to ‘text from url’.
Response URL set to: ‘http://listofcities.com/list?format=text’
Error URL set to: ‘http://listofcities.com/list?format=text&error=1’
Response conditions:
If response 0 – go to node: “Survey”
Last node/end session set to no.
Node name: “Location Check”
Response type set to ‘text from url’.
Response URL set to: ‘http://listofcities.com/list?format=text’
Error URL set to: ‘http://listofcities.com/list?format=text&error=1’
Response conditions:
If response 0 – go to node: “Survey”
Last node/end session set to no.
Node name: “Survey”
Response type set to ‘text’.
Response text set to:
‘Thank you, please rate the service you experience on a scale from 1 (very bad) to 5 (very good)’
Error text set to:
‘Please enter a number from 1 to 5 to rate the service you experience on a scale from 1 (very bad) to 5 (very good)’
Response conditions:
Complex condition: Greater than 0 and less than 6 – go to Node ‘Finished’.
Last node/end session set to no.
Node name: “Finished”
Response type set to text.
Response text set to:
‘Thank you for participating in our survey’
Actions
• Add user to address book list ‘Opted in users’
• Call URL ‘http://survey.com/complete’
• Email ‘complete@survey.com’
Last node/end session set to yes.
No error text or response conditions are set (irrelevant).
Sample user input and behavior
Now we can simulate a few scenarios based on the above data/campaign configuration.
→ Indicates a user sending a request/response to the service
← Indicates the service responding/sending text to the user
** Indicates the service performing an activity
For the purposes of these scenarios the user’s phone number will be 27831234567
Scenario 1
→ *100*123#
← Thank you for participating in our survey, please reply with 1 to confirm you accept our terms and conditions or enter 0 to decline.
→ Yes
← Please enter a valid response. Thank you for participating in our survey, please reply with 1 to confirm you accept our terms and conditions or enter 0 to decline’
→ 0
** Service moves to node “Terms declined”
← Thank you, you have opted out of our survey
** Session closes **
Scenario 2
→ *100*123#
← Thank you for participating in our survey, please reply with 1 to confirm you accept our terms and conditions or enter 0 to decline.
→ 1
** Service moves to node “Location Check”
** Service calls URL:
http://listofcities.com/list?format=text&ussd_msisdn=27831234567&ussd_session_id=51a6e12b-75f7-4d60-86a0-7f0635dd886e&ussd_request=1&ussd_type=2&ussd_node_id=3&ussd_node_name=Location+Check&ussd_response_Terms_and_Conditions=1
← Text received from URL returned to user screen
→ 3
** Service moves to node “Survey”
← Thank you, please rate the service you experience on a scale from 1 (very bad) to 5 (very good)
→ 4
** Service moves to node “Finished”
← Thank you for participating in our survey
** Service adds user number/msisdn to list ‘Opted in users’
** Service calls URL:
http://survey.com/complete? ussd_msisdn=27831234567&ussd_session_id=51a6e12b-75f7-4d60-86a0-7f0635dd886e&ussd_node_id=5&ussd_node_name=Finished&ussd_response_Terms_and_Conditions=1&ussd_response_Location_Check=3&ussd_response_Survey=4
** Session closes **