usssdd - vinemanuals.vine.co.za/docs/ussd_technical_description_v1_2.pdf · unstructured...

Version 1.1 of 25 07 November 2009

UUSSSSDD

Technical description

Version

1.1

Document location

On Owl at /Documents/Projects/USSD/USSD_Technical_Description_V1_0.docx

Date

7 November 2009

Support

For assistance, please contact Grapevine: +27 21 702-3333 or email [email protected].

Feedback

Was this document useful? What can we do to make this user guide more useful and informative? Please email [email protected] with your comments and feedback.

mailto:[email protected]

mailto:[email protected]

USSD Technical Description


Table of Contents

1. Introduction .................................................................................................................. 3

1.1. Overview ..................................................................................................................................... 3

1.2. Common applications of USSD technology ................................................................................ 3

1.3. How does Grapevine’s USSD interact with a client application? ................................................ 4 1.3.1. USSD prompts ................................................................................................................ 4 1.3.2. The USSD Gateway ......................................................................................................... 5

2. How does Grapevine use USSD technology? .................................................................. 6

2.1. The passage of a message over a network ................................................................................. 8

2.2. About USSD strings ..................................................................................................................... 9

2.3. About message types .................................................................................................................. 9

2.4. About response types ................................................................................................................. 9

2.5. About initStates ........................................................................................................................ 10

3. Types of USSD usage .................................................................................................... 11

4. Format of the USSD XML file ........................................................................................ 12

4.1. The USSD schema ..................................................................................................................... 12

4.2. Example of USSD definition XML and explanation of tags ....................................................... 15

5. Communicating with USSD ........................................................................................... 19

5.1. Initial request XML <USSDAppRequest> ................................................................................... 20

5.2. Initial response XML <USSDAppResponse> .............................................................................. 20

5.3. Action request XML <USSDAppRequst> ................................................................................... 20

5.4. Action response XML <USSDAppResponse> ............................................................................. 21

6. Appendix A – additional examples ................................................................................ 21

6.1. Bank account balance request .................................................................................................. 21

6.2. Top up pre-paid account balance request ................................................................................ 22

6.3. Regional weather request ......................................................................................................... 24

6.4. Competition entry ..................................................................................................................... 25

Abbreviations

GSM Global System for Mobile Communication GVI Grapevine Interactive IM Instant Messaging NI USSD Network Initiated Unstructured Supplementary Service Data SMS Short Messaging Service USSD Unstructured Supplementary Service Data WAP Wireless Application Protocol WASP Wireless Application Service Provider XML eXtensible Markup Language XSD eXtensible Schema Definition



1. Introduction

1.1. Overview

Unstructured Supplementary Service Data (USSD) is a technology used to facilitate the transmission of multiple text messages between a mobile phone and a client application program across a mobile phone network. Its main feature is that it enables interactivity between a mobile phone user and a client application, at high speed and in real time. USSD appears similar to Short Messaging Service (SMS), but USSD is session-based and multiple USSD messages are transmitted during a session. To understand the difference between USSD and SMS, USSD can be compared to Instant Messaging (IM) which is immediate and continuous until broken by one of the communicating parties, while SMS can be compared to email, which is a single, once-off communication. USSD messages, unlike SMSs, are not stored and forwarded, or sent to a phone’s Inbox. USSD messages are displayed directly on a phone’s screen when they are sent during a USSD session. USSD transactions are more cost-effective than SMS transactions because USSD transactions are typically billed at a low per second rate as long as a session is open, rather than per transaction as is the case with SMS. The benefit of USSD technology is that it is supported by most GSM mobile phones, and no extra software is needed to make use of it.

1.2. Common applications of USSD technology

USSD is most commonly used to make it easy for a prepaid mobile phone user to query a prepaid account balance or top up a prepaid account. But USSD has many other uses:

Mobile chatting

“Please call me” requests

Campaigns and competitions

Surveys

Subscription services

Downloads

Enquiries

Remote transactions

Browsing information via text menus

Services, e.g. online gambling

http://searchmobilecomputing.techtarget.com/sDefinition/0,,sid40_gci213660,00.html



1.3. How does Grapevine’s USSD interact with a client application?

In the following examples you can see that Grapevine’s USSD can interact with a client application in two different ways. In the first example USSD interacts with the mobile phone user by sending prompts that it reads from an XML file. USSD analyses the mobile phone user’s responses, e.g. a menu selection, and responds by either sending another prompt to the user or by sending details of the user’s input to a client application. In the second example, USSD simply passes strings of data from the mobile phone user to the client application, and from the client application to the mobile phone user. In this scenario, USSD doesn’t analyse the data. Note: In both examples, the data is transported using XML files.

1.3.1. USSD prompts An example of a request for an account balance is shown below:

....

....

Application

programUSSD

User dials *120*1043# <send>

Welcome to VodaTel.

Please enter your name followed by your

cell phone number

User enters 1 <send>

Account info menu: 1 – Payments, 2 –

Balance, 3 – Return to Main menu


USSD passes „2 - Balance‟ to

application program

Application validates parameter,

retrieves balance and returns

response

Your account balance is R30.75. Thank

you for using VodaTel

User enters joe 0731234567

<send>

Hello joe. What would you like to do

today?

Main menu: 1 – Account info, 2 –

Downloads, 3 - Help

Init State = FIXED

Response type =

STRING

Response type =

MENU

SELECTION

Response type =

MENU

SELECTION

Figure 1 – requesting an account balance – USSD prompts

1. A USSD session is initiated by a user entering a string of symbols and digits on a mobile phone, e.g.

*120*1043#. In our example, this string is a request for a pre-paid mobile phone account balance. 2. The USSD application responds by sending a ‘Welcome ...’ message back to the user in a text string,

asking for his name and mobile phone number. This is called a prompt. 3. The user enters his name and mobile phone number. This is called a response. 4. USSD now sends a text menu prompt to the user. 5. The user selects a menu option, e.g. 1. 6. USSD now sends a sub-menu prompt to the user.



7. The user selects a menu option, e.g. 2. 8. It is only at this point that the USSD application passes the menu selection response to the client

application, using an XML file. 9. The client application extracts the user’s account balance and sends this balance back to USSD using

an XML file. 10. The USSD application sends the balance to be displayed on the user’s mobile phone.

Behind the scenes: Up until Step 8, the USSD application handles all the responses from and prompts to the user using XML files that transport prompts to the user and responses from the user. When all the required data has been accumulated from the user, USSD generates an XML file containing the parameters needed by the client application to process the request. It then waits for a response XML from the client application. What happens behind the scenes in USSD depends on the nature of the initial request made to the USSD application. In Figure 1 you will see the comment (Init State = FIXED). This means that no parameter has been included in the USSD string sent by the user and therefore USSD should handle the first prompt to the user. The USSD string sent by the user was *120*1055# Compare this to the scenario where the user sends a USSD string including a parameter to USSD, e.g. *121*1056*12906435810#. In this case the Init State = URL. The fact that there is a parameter triggers USSD to first connect to the client application where the initial prompt to the user can be found. We will learn more about Init States in: 2. How does USSD work?

1.3.2. The USSD Gateway

USSD can also facilitate the interaction between a client application and a mobile phone user by operating purely as a gateway. In this scenario, USSD simply passes transactions between the client and the phone user without analysing them, i.e., it does not interpret responses by the user and determine at what stage the client application should be invoked. This scenario is most often used when a client writes their own application and wishes to control all transactions completely. Let’s contrast how this would work if we used the same example as we did in Figure 1.



....

....

Application

programUSSD


Welcome to VodaTel.


cell phone number





Your account balance is R30.75.

Thank you for using VodaTelYour account balance is R30.75. Thank



<send>


today?


Downloads, 3 - Help

Init State = FIXED

Response type =

STRING

Response type =

STRING

Response type =

STRING

MSISDN

Welcome to VodaTel.


cell phone number

joe 0731234567


today?


Downloads, 3 - Help

1

2



Figure 2 – requesting an account balance – USSD gateway

Behind the scenes: In this example, USSD application simply passes strings of data between the user and the client application using XML files.

2. How does Grapevine use USSD technology?

USSD transmits multiple text messages between a mobile phone and a client application program. The transmission of these messages comprises a series of prompts (requests) and responses between phone and USSD application, and between USSD application and client application (see Figure 3).

Important: Message transmission terminology can seem confusing. When we refer to a message sent from a mobile phone to USSD, we use the term “response” except for the original process-initiating message. When we refer to a message sent from the USSD application to the mobile phone user, we use the term “prompt” (except for the final process-terminating message) as we are continuously trying to “prompt” a “response” from the user.

To do this, Grapevine uses an XML file that describes how to route the USSD transactions, either to the user with a menu or prompt, or to the back-end application with a request. The XML file is always created for clients by Grapevine. Grapevine can create the back-end application as well, or clients can create their own back-end applications. What clients need to know is the format of the XML files they will receive from USSD (containing the data input by the user) and the format of the XML files they will need to send to USSD (containing the prompts to the user). (See 5. Responding to a Grapevine request).



....

....

Client

Application

USSD

Application....

....

XML definition file

XML

Figure 3 – Grapevine’s USSD

Notes:

An XML file only describes and transports text; it does not define the format of text or validate it.

There are five XML files. The first USSD XML file is a definition file used by the USSD application program to determine what text to send to the mobile phone as a prompt depending on the response of the user: the response from the user can be either a string or a menu selection. The other four XML files are used to transmit data between USSD and the client application.



2.1. The passage of a message over a network

....

....

Client

Application USSD

Vodacom

MTN

Cell C

USSD

managers

Mobile phone

requests

....

....

....

....

GVI USSD

application

Client

application

1 2 3 4 5 6 7

Figure 4 – the passage of a message over a network

1. A USSD session is activated by a mobile phone user typing a string of characters comprising an

asterisk (*), followed by a number of digits and ending with a hash (#), e.g. *120*127#. A mobile phone handset recognises these characters as a USSD string, and uses a USSD bearer or manager to transmit a text message request to a client application instead of making a voice call (see 5 above).

2. The initial request by the mobile phone user is first routed to a mobile phone operator. The request is then routed via the network operator’s USSD manager to Grapevine’s USSD application and then to a client application program, which, in turn, sends a response back to the mobile phone.

3. Because a large number of users may be accessing USSD at the same time, the network operators’ USSD managers will create unique session IDs for each session, so that as messages stream back and forth the session, they belong to can be identified. The session ID is one of the parameters the client application will always receive from USSD in an XML file. (Another is the MSISDN.)

4. Every session begins with an initial state that determines how to route the first message. Messages sent from the user are called responses (except for the initial message) while messages sent to the user are called prompts (except for the final terminating message).

5. Each request and response in a USSD session is called a transaction. USSD inspects these transactions and routes them to the client application, or compiles a new prompt, e.g. a sub-menu, to be sent to the user.

6. When it is required to send user data to the external client application, Grapevine performs an HTTP post of name / value pairs. If the client application has not been developed by Grapevine, it may be necessary for the data sent by the USSD application to be translated into a format recognisable by the client application. An example of a name / value pair would be <name>idnumber</name> / <value>7210120176081</value>.

7. The message sent to a client application will include parameters. The client application now uses the parameters to prepare its response which will be routed to the user via USSD.

Note: A client application may be a custom application written by Grapevine for a client or may be an application a client already has. Grapevine writes the XML that will be used by all client applications. You, the client, needs to know the format of the XML which you will receive from USSD and the format of the XML which you need to send back to USSD.



2.2. About USSD strings

USSD originating requests always include a USSD string. A USSD string comprises an asterisk (*) followed by a number of digits and ending with a hash (#), e.g. *120*127#. A USSD session is initiated by the transmission of a unique USSD string that identifies the request, and enables the network operators to route the request so it can be processed by the correct WASP. USSD strings are provided to a WASP, like Grapevine, by the network operators and each string is reserved for an specific application or request.

Note: Many people will recognise the USSD string to request an account balance: *121#. Grapevine’s USSD strings usually use two asterisks and a hash. For instance, a request to enter a particular competition may look like this: *2020*1535#. A USSD string with a parameter, e.g. a voucher number, may look like this: *2020*1535*29283928#

2.3. About message types

There are three types of session messages:

Originating message – an originating message is the first message sent (always initiated in the Grapevine process by a mobile phone user) to start a session and always contains a USSD string, e.g., *127*2020*1575#. The 1575 in the string is a parameter; this indicates that USSD needs to send the request to the client application.

Data messages – a series of requests and responses that comprise the text prompts and responses between a mobile phone and a client application, or a mobile phone and the USSD application.

Terminating message – a terminating message ends a session and transports the final piece of content that may be sent by the client application, e.g., Thank you for entering this competition. If a mobile phone user simply switches off their phone, the terminating message will be sent by the USSD manager that is managing the session. Alternatively, the terminating message will be triggered by a keyword in the XML that is recognised by the USSD application, e.g., “End”.

2.4. About response types

A USSD session comprises a series of requests and responses moving between mobile phone, network operator, USSD and client application. You need to understand the two types of message response that a user can make because when you design your service, how the XML definition file is configured will depend on what type of response you are expecting from the user. There are two response types:

Menu type response – A menu is a set of options presented to a user. A menu selection is the option a user chooses. So, a menu type response is always a menu selection.

Menu Menu selection response

Hello joe. What would you like to do today?

Main menu: 1 – Account info 2 – Downloads

3 – Help

1

Figure 5 – menu type response

String type response – A string is comprised of a set of characters that can also contain spaces and numbers. To all intents and purposes, it can contain anything. A string is usually elicited from a user



as a response to a question or request for information. So, a string type response is always a string of characters and spaces.

Request String response

Welcome to VodaTel.

Please enter your name followed by your mobile phone number

joe 0731234567

Figure 6 – string type response

Note: USSD messages can contain up to 160 characters, including spaces, just like an SMS.

2.5. About initStates

Important: There are five XML files. The first USSD XML file is used by the USSD application program to determine what text to send to the mobile phone as a prompt depending on the response of the user: the response from the user can be either a string or a menu selection. A client does not need to know how this file is set up. The other XML files contains the data passed between USSD and the client application. See 5. Communicating with USSD.

The initial state (initState) of a session describes where the first prompt (message) sent back to the user (after the message is initiated by the mobile phone user by sending a USSD string) can be found. The initState is set up in Grapevine’s XML schema. In the USSD definition XML, the initState type tag tells the USSD application whether or not the initial state needs to be fetched from the client application program or not.

Note: The initState tag must not be confused with the state tag. The initState tag defines which is the first state tag to be used. The state tag describes a particular step in the process, e.g., a Welcome message.

If the initial state needs to be fetched from the client application, the initState type tag is ‘url’. If the initState type tag is ‘url’, the initState name tag contains a URL. When the initState type tag is ‘url’, the user will have entered a parameter.

If the initial state is already known, the initState type tag is ‘fixed’. If the initState type tag is ‘fixed’, the initState name tag contains the name of the first state. When the initState type tag is ‘fixed’, the user will not have entered a parameter.

Summary: What the above means is that when an initState type is ‘fixed’, the prompt for the user is already in the XML and a prompt doesn’t need to be requested from the client, and when the initState type is ‘url’, it does. An example of the former is when the USSD definition XML may already contain the text “Welcome to Fin Banking”. An example of the latter is when the client needs to validate the parameter typed by the user. As mentioned in the note above, prompts in the USSD definition XML are contained in the state tags.

Fixed initState type – the USSD string does not include a parameter when the iniState type is ‘fixed’. In the example below, the name of the first state – ‘Welcome’ in the example below - is described in the initState name tag.



Figure 7 – fixed init state

URL iniState type–the USSD string includes a parameter when the iniState type is ‘url’. This parameter is sent to the client application program. In the example below, the address of the client application is described in the initState name tag.

Figure 8 – URL init state

The reason the XML is set up in this way is to be able to have flexibility as to which message is the first prompt sent to the mobile phone.

3. Types of USSD usage

Although there are many uses of USSD, there are two primary types and these are categorised according to response types (response types are transactions triggered by a mobile phone user):



1. Menu type– A menu is a set of options presented to a user, e.g. ‘1, 2, 3’ or ‘a, b, c’. A menu selection

is the option a user chooses.

2. String type– A string is comprised of a set of characters that can also contain spaces and numbers. To all intents and purposes, it can contain anything. A string is usually elicited from a user as a response to a question or request for information. A string can contain a maximum of 160 characters.

Messages that don’t fall under one of the above types of response are messages that are sent by an application without expecting a response, e.g.: the terminating message “Thank you for entering this competition”.

4. Format of the USSD XML file

Grapevine’s USSD application uses a standard eXtensible Markup Language (XML) file to populate the messages that are sent to a mobile phone during a USSD session. Some messages are populated by output from the application program, but the advantage of USSD is that it can handle a simple conversation with a mobile phone all on its own. It does this using menus and text that are contained in the XML definition file. It also uses the XML file to identify the URL of the client application program and the parameters to be passed to the application. Let’s take a look at how this works.

Note: USSD messages can contain up to 160 characters, including spaces, just like an SMS.

4.1. The USSD schema

All applications that use Grapevine’s USSD will use the USSD schema which describes the structure and determines the contents of the XML definition file. Let’s first take a look at the USSD XML schema and then we will look at the XML used to create an example XML session. We will conceptually divide the XML into sections 1 to 4 to make it easier to follow the logic.

Note: The view of the communication flow below will Grapevine design a custom XML file for a client application.



....

....

Application

programUSSD


Welcome to SuperSubs.

Before selecting a subscription, please

enter your name


User enters jane brown<send>

Thank you. To which service would you

like to subscribe?

1 – Weather, 2 – News

Init State = FIXED

Response type =

STRING

Response type =

MENU

SELECTION

Session

start

Session

end

USSD passes „2, jane brown‟ to

application program

Application stores user details – name,

mobile number and type of user

subscription (e.g. News). It then creates

a user password and sends password

and web site URL to the user.

Congratulations jane brown. Your

username is 0731234567 and your

password is 712Xa3. Log in to the

SuperSubs News web site at:

www.supersubs.news.co.za

Figure 9 – SuperSubs application

Now let’s take a look at the Grapevine USSD XML schema (XSD) below that is used to create the XML for the above example.



Section 1

Section 2

Section 3

Section 4

Figure 10 – XML schema

Notes:

In the above diagram, the fields in the boxes with dotted line are optional.

We will conceptually divide the XML into sections 1 to 4 to make it easier to follow the logic.



4.2. Example of USSD definition XML and explanation of tags

Note: The XML below is an example only. Section 1 The first section of the XML definition file contains: header information, the name of the campaign (in this case, a request to subscribe to an information service), the start and end dates in between which users may subscribe, and the initial state of the campaign. The initial state of this example session is ‘fixed’. The state containing the first prompt in this session is defined in the name tag.

Tag Explanation

Section 1 explained Notes:

Fields in boxes with a dotted line in the XML XSD schema are optional, e.g. start date and start message, and end date and end message. In our example, we haven’t entered a start date or message.

A state tag in the XML defines a step in the campaign.

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\Users\Laura\files\ussd\schema.xsd">

USSD-specific header information

campaignName Name of the application, e.g., SuperSubs (which is a subscription service)

affiliateCode The affiliate is the company provisioned by Grapevine to use a service like USSD, e.g. SUP001.

End

end date End date of the campaign, e.g. “2009-12-31”. This date will be validated by the USSD application and if the validation fails, an end message will be sent to the mobile phone, e.g. “This service is no longer available.”

end message “This service is no longer available.”

initState

initState type The initState type can be’fixed’ or ‘url’. If the initState type is ‘url’, the USSD application will look for a parameter entered by the user.



It will then send this parameter together with a URL defined in the XML to the client application program in order to retrieve the initial state. It will use the URL defined in the initState name tag. If the initState type is ‘fixed’, the USSD application will use the state defined in the initState name tag in the XML. In the example above, the initState type is ‘fixed’ and it is called “Welcome”.

initState name If the initState type is ‘fixed’, the iniState name is the name of the initial state. If the initState type is ‘url’, the initState name is the URL that, together with the parameter entered by the user, must be passed to the application program.

Section 2 The second section of the XML file contains information about the prompts that need to be sent to the user and the responses received from the user. In the example below, the prompt tag contains the text message sent to the user prompting the type of response defined in the responseType tag, i.e. “string” or “menu”.

Tag Explanation

Section 2 explained

States

states name Name of the state, e.g. “Welcome” or “Subscription”.

states prompt Text message that is sent to the mobile phone, e.g. “Welcome to SuperSubs. Before selecting a subscription, please enter your name” or “Thank you. To which service would you like to subscribe? 1 - Weather 2 – News”.

states responseType The menu response type refers to the type of response elicited from a user, i.e. a

string type response or a menu selection response. In the example above, the

first prompt will elicit a string response that is expected to be in string format (the

user’s name), and the second prompt will elicit a response that is expected to be

a menu selection (e.g., 2).



Section 3 The third section of the XML file contains information about the action needed when all the information needed from the user has been received. When all the information required from the user has been gathered, the sendAction tag is “true”. This means the data can be sent through to the client application.

field: Prompted by request for user to enter name

field: Prompted by request for user to select a type of

subscription

nextState: After user selects type of subscription, the process ends and the parameters are sent to

the client application

nextState: After user selects type of subscription, the process continues to the

selection of a type of subscription

SuperAction: Defines the tag that sets up these parameters for the

call to the client application

Tag Explanation

Section 3 explained Note: The tags in this section, except for the nextState tag, are optional.

responseType The responseType to the type of response elicited from a user, i.e. a string or a

menu selection. In the example above, the first prompt will elicit a string

response (the user’s name), and the second prompt will elicit a menu selection

(e.g., 2).

Responses

response txt The menu selection entered by the user if the responseType is “menu”. If the responseType is “string”, this field will not be included in this section.

response save An optional field that is used to redefine the menu selection, e.g. if option 2 is News, instead of sending the client application program the digit 2, the words “news” can be sent instead.

response field Name of the state, e.g., name (where the user’s name, joe, was retrieved) or subscription (where the user’s subscription preference – news - was retrieved).

response action Name of the action tag. A session may include more than one action. In our



example, there is only one action which you can see in the rightmost responsibility column. This is the action between the USSD application and the client application program. An action contains the parameters sent to the client application.

response sendAction Default is “false”. This tag indicates whether all parameters have been retrieved that are required to send to the client application program. The default shows that all the data has not yet been retrieved.

response nextState In the first response in the above example, the nextState, after retrieving the user name, is “Subscription”. Note: When the nextState is “end”, the USSD application recognises “end” as a keyword indicating that this is the final nextState. It will send the last message passed by the client application, e.g. “Thank you for entering this competition”, to the mobile phone. This keyword, and the transmission of the final message, triggers the end of the session.

Section 4 The fourth section of the XML file contains the URL of the client application and the fields that need to be passed to it. Actions will be activated when the sendAction tag in Section 3 above is “true”.

Tag Explanation

Section 4 explained Note: The user’s MSISDN will always be passed to the client application program by the USSD application. It is not part of the XML however. Actions might also include fields like the session ID.

Actions

action name Name of the action if required. If the initState is ‘url’, this will be the location of the client application program, else it will be the name of the state in the Grapevine XML that will process the request. The action name is always capitalised.

action url The URL of the application program.

action field (multiple) Fields are passed to the application program as parameters, e.g. the user’s name

and their menu selection.

field name Name of parameter, e.g. name. The name of the parameter is always in



lowercase.

field value Value of parameter, e.g. JoeBloggs.

5. Communicating with USSD

As messages move between the mobile phone user and USSD, USSD stores the data it receives. It then composes an XML to send to you, the client, with the parameters entered by the mobile phone user. Your application will use these parameters and compose a response XML to send to USSD to be passed on to the mobile phone user. This response could be a prompt to the user requiring further information (e.g. “Your login was successful. Please select your next transaction”) or it could be a terminating message (e.g. “Thank you for using Vodatel”). There are two request XML formats and two response XML formats.

Initial request XML (the first request sent by USSD to the client application)

Action request XML (these are the requests that are sent by USSD to the client application except for the first request)

Initial response XML (the first response sent by the client application to USSD)

Action response XML (these are the responses that are sent by client application to USSD except for the first response)

In the example below, we are going to assume that you, the client have decided that you want to handle all the messages yourself. Therefore, the response type from the user will always be in the form of a string. The reason for this is that USSD will not analyse the menu selections that the user makes. In this example, the Initial state type = URL.

....

....

Application

programUSSD

User dials *120*1043*99# <send>





“Your account balance is R30.75.

Thank you for using VodaTel” “end”Your account balance is R30.75. Thank



<send>


today?


Downloads, 3 - Help

Init State = URL

Response type =

STRING

Response type =

STRING

Response type =

STRING

“initial” “0731234567” “87123456”

“99”

“Welcome to VodaTel.


cell phone number” “initState”

“initial” “0731234567” “87123456”

“joe” “0731234567”

“Hello joe. What would you like to do

today?


Downloads, 3 - Help” “ “

“action” “0731234567” “87123456”

“field” “1”

“action” “0731234567” “87123456”

“field” “2”

“Account info menu: 1 – Payments, 2 –

Balance, 3 – Return to Main menu” “ “

“Welcome to VodaTel.


cell phone number”

Figure 11 – request for an account balance



Now, let’s take a look at the XML files that you as an Affiliate can expect to receive from Grapevine and the format of the response XML files you need to reply with.

5.1. Initial request XML <USSDAppRequest>

Below is a sample of the first request XML file that will be sent to your application to which you have to respond: <USSDAppRequest> <type>initial</type>

<msisdn>0731234567</msisdn> <sessionId>721082474</sessionId> <parameter> </parameter>

</USSDAppRequest> Notes:

<type> is always “initial” for the first request.

<parameter> will include user input, if any.

5.2. Initial response XML <USSDAppResponse>

Below is a sample of the first response XML file that you will need to send back to USSD in response to USSD’s first request: <USSDAppResponse>

<prompt>Welcome to Vodatel. Please enter your name followed by your cell phone number</prompt> <state>name of the initState</state>

</USSDAppResponse> Note: <state> indicates to USSD where in the definition XML it needs to go next.

5.3. Action request XML <USSDAppRequst>

Below is a sample of a request XML file (after the first one) that will be sent to your application to which you have to respond: <USSDAppRequest>

<type>action</type > <msisdn>0731234567</msisdn> <sessionId>721082474</sessionId> <name>accountbalance</name> <fields>

<field> <name>account</name> <value>2</value>

</field> </fields>

</USSDAppRequest>



Notes:

<type> refers to the type of XML, in this case action, as opposed to “initial” which is the first type of request.

<name> is the name of the action.

field <name> is the name of the field.

field <value> in this instance is the menu selection made by the user.

5.4. Action response XML <USSDAppResponse>

Below is a sample of a response XML file that you will need to send back to USSD in response to a USSD request (after the first one): <USSDAppResponse>

<prompt>27731234567</prompt> <state>end</state>

</USSDAppResponse> Note: <state> indicates to USSD where in the definition XML it needs to go next. If this field is blank, it means that USSD needs to continue to pass strings of data between the client application and the mobile phone. If <state> is “end”, it means the session should be ended.

Important: These are examples only. The tags in the XML files will vary depending on the requirements of individual applications.

6. Appendix A – additional examples

Note: In the examples below we are using USSD to format some of the prompts to the user. We could also use USSD purely as a portal in which case the client application would format all the prompts. In this scenario USSD would simply transmit strings of data between the user and the client application.

6.1. Bank account balance request

In this example, a user requests his bank account balance via Grapevine’s USSD. The menus presented by the USSD application are developed by Grapevine according to client specifications and allow the user to browse through various USSD services offered by the bank.



....

....

Application

programUSSD


Welcome to Top National Bank.

Please enter your cell phone number


Banking application validates

parameters, retrieves balance and

returns response

Your available balance is R3000.75.

Thank you for banking with Top National

Bank.


Thank you. What would you like to do

today?

Main menu:

1 – Account info

2 – Account Balance

3 – Customer Service

Thank you. Please enter your account

number

Thank you. Please enter your ID number

User enters c10H45 <send>

User enters

6510200177071<send>

USSD passes „0731234567, 2 –

Account Balance, 97451092,

c10H45, 6510200177071‟ to

banking application


Thank you. Please enter your secret pin

number

6.2. Top up pre-paid account balance request

In this example, a user enters a USSD string and voucher number to top up the prepaid account balance on his mobile phone. The request, including the voucher number parameter, is routed directly to the network operator and the user’s account balance is topped up immediately.



....

....

Application

programUSSD

User dials *1320*1012*534984012#

<send>

USSD passes

„*1320*1012*534984012#‟ to

network operator application

Network operator application

validates voucher number and

returns response

Your account has been credited with

R100. Your balance is R101.35. Thank




6.3. Regional weather request

In this example, Grapevine’s USSD allows a user to browse SA Tourism Portal USSD services. The user chooses to view the weather for his region. The menus for this service are developed by Grapevine according to client specifications.

....

....

Application

programUSSD


Welcome to the SA Tourism Portal.

What would you like to do today?

Main menu:

1 – Make an enquiry

2 – Book accommodation

3 – Request a call back

4 - Download a brochure


SA Tourism Portal application

retrieves regional weather and

passes it to the USSD application

Gauteng will be warm and dry tomorrow

with no wind but with a 30% chance of

light drizzle in the evening: 18C – 26C.


Thank you. Please select a region:

1 – Western Cape

2 – Gauteng

3 – Northern Cape

4 – North West Province

5 – Eastern Cape

6 – Mapumalanga

7 – Free State

8 – Limpopo

9 – Kwa-Zulu Natal

User enters „2‟ <send>

USSD passes „2‟ to SA Tourism

Portal application

Thank you. What type of enquiry would

you like to make?

1 – Sport scores

2 – Surf report

3 – Local news

4 – Restaurants

5 – Accommodation

6 – Weathera


of 25

For assistance, please contact Grapevine: +27 21 702-3333 or email [email protected].

6.4. Competition entry

In this example, a user enters the Sporting Heroes Competition. He sends a USSD string and the answer to the competition question directly to the WinALot company that is holding the competition. WinALot enters the user’s mobile phone number into the competition draw and sends a message to the user, telling him he will be notified if he wins the compeition.

....

....

Application

programUSSD

User dials *1320*1014*beckham#

<send>

USSD passes

„*1320*1014*beckham#‟ to WinALot

application

WInALot application stores user‟s

competition entry and sends a

response to the USSD application

Thank you for entering WinALot‟s

Sporting Heroes Competition. You will

be notified if you have won a prize