USSD Menus

From txtNation Wiki
Jump to: navigation, search

Beta

USSD Menu Gateway

txtNation USSD Menu Gateway can be used to deploy a reliable, low cost USSD-based menu platform into your new or existing RESTful platform. Our USSD Menu Gateway enables businesses to facilitate real-time communication between themselves and their mobile subscribers.

The aim of this article is to guide you through the integration of our USSD Menu Gateway with your own platform. If you have developed RESTful services before, you should find this document relatively easy to follow. If you have any questions that are not covered by this document or in the FAQs please contact our dedicated Client Support site.

USSD Mode

(txtNation USSD menu gateway API is a Mode 2 service)

Mode 1. Mobile Initiated USSD / PULL USSD / P2P The consumer dials *139# from there GSM mobile handset. The mode known as USSD PULL / Mobile initiated

Mode 2. Network Initiated USSD / PUSH USSD / A2P The consumer receives a push message from network. This is USSD PUSH mode / request initiated by network. This may be used for promotions or delivering one time passwords or Pin's. The service can be initiated in a variety of ways, for example the consumer sends a standard SMS containing a keyword, to either a shortcode or a longcode. The MSISDN from the Consumers (MO) SMS can then used to start the USSD menu service.


Important Information

Any country connection problems or interruptions to txtNation services will be announced in our Zendesk forum article found here: Please login to / create your Zendesk account and subscribe to these updates now, they will be very important for your services. If you are a temporary developer on a project, please advise your employer to do the same. Scheduled maintenance periods can also be subscribed to here.


Contents


Implementation

In order to implement a USSD menu you will need:

  1. Good programming knowledge to create a script that can respond to HTTP GET/POST requests.
  2. Access to a handset that supports USSD menus.
  3. A server to which txtNation can send real-time communications from your end users.

Note: As default the request is sent as a form POST and you can respond in JSON or XML, however if required we can also send the initial REQUEST in JSON or XML rather than the form POST.

Quick Reference


Common Gateway Responses

G-103 : An invalid ekey / cc variable has been set and posted to us. (These are case sensitive)

G-104 : Invalid details. Unable to find matching session. Please check the "number" and "session_id" you submitted matches the one posted to you for the request.

G-404 : Missing MSISDN. We need to know the phone number to which you wish to send.

G-405 : Phone number not numeric. Please note that all phone numbers need to be numeric.

G-415 : cc variable not found. The cc variable value you have set is not recognised.

E-100 : Please contact support for more assistance.

Getting Started

You need to contact txtNation Client technical Support to ensure that USSD menus are enabled on your account. This is best achieved by raising a support request at http://clients.txtnation.com/ If you do not have a password, then you can obtain one at http://clients.txtnation.com/access/help

Information you will need to provide in the support request

Your txtNation Account Name as found at the top right of the txtNation CP (Control panel) when you login https://secure.txtnation.com/index.php

Location of your USSD menu receiver

Give the full URL (e.g. http://yourdomain.com/scripts/responder.php) of the file on your server which will process the POST requests from our server to a member of our support team.

Initiating a USSD Menu

This is achieved by initiating an HTTP POST or GET request to the URL: http://ussd.txtnation.com/gateway

Whether you are sending a direct reply to an incoming message, a scheduled subscription message or a free advertising message, the below variable set should be used.

Below are the variables that we expect from you in response to a USSDM request:

Variable Name Description
number The MSISDN to which you are sending the USSD menu. This should be in full international format including the country dial code and without leading zeros or the + symbol.
cc The company name you use with us
ekey The ekey assigned to you


Example Request

   http://ussd.txtnation.com/gateway?number=447777777777&cc=your_company&ekey=your_ekey

Response

When your correctly formatted posts hit the txtNation gateway server, we will respond with the new Session ID e.g. 51e172c5aea646.46313236. We recommend you store this Session ID as it will be used in future requests by us when requesting menu content. If an error occurred, an error code will be displayed in the format G-XXX or E-XXX (see Common Gateway Responses). It is recommended that you store all txtNation responses in order to assist txtNation technical support debug any errors.

Post Variables (txtNation to you)

Below are the POST variables we will send to you when we receive a USSD menu request:

Variable Name Example Contents Description
action open_session or prompt_rsp When a new USSD menu session is opened, we will send the open_session action. You script will then respond with the initial menu content. Any additional requests for matching session IDs if you replied with prompt_req will have the prompt_rsp action and will contain your req_id identifier and user response.
session_id 51e172c5aea646.46313236 The unique id of the session which is passed to you
number 447890123456 The MSISDN of the end user initiating the session
datetime 2013-07-15 00:00:00 The time that the menu was requested
req_id 1 Your internal menu identifier. This is generally an incremental count to track the menu count and to identify a menu response.
response Hello world! The contents of a user's message is formatted and sent to you in this variable
debug 1 If a request was generated from the emulator in your USSD menu control panel it will have debug variable set. These requests are not sent to a handset and are instead routed to the emulator in real time. If a request is generated via the emulator, the originating number will appear as 4477[YEAR][MONTH][DAY] e.g. 07720130130 for 2013/01/30

Note: Options for JSON / XML requests - If you require the request to be sent in JSON or XML, please contact txtNation support.

XML / JSON Response (You to txtNation)

Below are the variables that we expect from you in response to a USSD menu request.

Variable Name Example Contents Description
req_type prompt_req or display_req The type prompt_req indicates that you expect a response from the user. The type display_req is a simple display of content, and is often used at the end of a menu flow.
session_id 51e172c5aea646.46313236 The unique id of the session as passed to you by txtNation
message Hello world! The menu content to send to the end user, Max 187 Chars, GSM Char set.
version 1.0 The version of the Gateway you are using, enclosed in double quotes. If not given, it will be assumed you are using the latest version (optional) [data should be enclosed in double quotes e.g "1.0"]
req_id 1 Your internal menu identifier. This is generally an incremental count to track the menu count and to identify a menu response.


Additional Variable Information

Variable Name Description
req_type The type prompt_req indicates that you expect a response from the user. The type display_req is a simple display of content, and is often used at the end of a menu flow.
req_id Your internal menu identifier. This is generally an incremental count to track the menu count and to identify a menu response.
response The reply as entered by the user.


Example JSON Response (Your service to txtNation gateway)

   {"version":"1.0","req_type":"prompt_req","message":"Welcome to the USSD demo!\n\nPlease enter your name:","session_id":"51e172c5aea646.46313236","req_id":1}

Example XML Response (Your service to txtNation gateway)

   <?xml version="1.0"?>
   <umsprot version="1">
       <prompt_req req_id="1" session_id="51e172c5aea646.46313236">Welcome to the USSD demo! Please enter your name:</prompt_req>
   </umsprot>

If you are using XML don't forget to set the application/xml HTTP header in your response. PHP e.g.

  header('Content-type: application/xml');

Additional Setup Recommendations

Request Content Type

If you prefer, we can also post to your script using JSON or XML rather than as a application/x-www-form-urlencoded request. Please let us know if you wish this to be changed on your account.


Response Content Type

In order for us to detect and accurately process your response, ensure to set your content header to application/xml or application/json as applicable.

This can be done in PHP using the code:

   header('Content-type: application/json');


Request Retries & Timeout

As the Gateway reacts realtime to requests, it is not appropriate to issue retries, and the timeout is limited to a maximum of 60 seconds.

Implementation Examples & Testing

Sample Script

You can download sample scripts from here:

JSON EXAMPLE SCRIPT
XML EXAMPLE SCRIPT

Once downloaded please extract the file "responder.php". You will need to edit the file to add any custom code (such as database inserts and menu handling). Once done it will need to be uploaded to a server that supports PHP (version 5+). Its location can then be entered on the control panel and a test sent to it from a handset or the USSD menu emulator. If you require assistance with this please contact our support team at: http://sd.txtnation.com.

Testing your service

Now your responder script is in place your probably going to want to start a menu session and tweak the menu responses. This can be done by sending the keyword you have requested upon setup to one of the shortcodes you have been assigned or using the USSD menu emulator.

If you require testing from a country you have not purchased for your service, please first check http://xml.txtnation.com/xml to see if it is available and consult with the support team.


Error Reporting

Because your script outputs in response to a txtNation server request, there is no realtime feedback if an error is encountered.

If error reporting is enabled on your account, Client Support can provide you with further information. Alternately, use the USSD menu emulator which will give you more information and help you to debug any errors.


USSD Menu Gateway - Implementation - Step by Step

Getting Started

Login to txtNation USSD menu Control Panel, available at http://ussd.txtnation.com/client.

If you are unable to login using your txtNation account, you may not have USSD menus set up on your account.

This is the main hub of the USSD Menu Gateway, your USSD menu account, and testing.

Configure your responder

You may amend the example responder script, or create your own, which should update the received data to your database, then construct the next menu item which can then be posted back to the txtNation USSD Menu Gateway for onward transmission to the end user.

Testing

Use the USSD menu emulator to test your script and current configuration, which will help you to debug any errors.

Personal tools