Getting started with USSD

The Hubtel USSD API acts as a gateway linking USSD service applications to a GSM network in a session oriented communication.

It routes USSD sessions from a GSM network to service applications and the other way round. Being a session oriented communication channel' means when a user dials a USSD code, a connection is established between the mobile user's handset and your application.

This connection has to be maintained for the real-time transmission of data to and from your application to the mobile user's handset.

How USSD Works

USSD is a protocol used to send text messages over Global System for Mobile Communications (GSM) networks. A typical USSD short code starts with an asterisk () followed by digits and terminates with a #. An example of a USSD code is 124#, used for checking mobile credit balance.

USSD is similar to SMS, but unlike SMS, it create a real time connection for a mobile user. This connection remains open during a session for two way exchange of data.

This makes USSD an ideal technology for rolling out Value Added Services (VAS) to enable instant and real-time interaction with mobile users.

Request for a USSD Code:

  1. Login to your Unity account.
  2. Click on Request USSD Shortcode under the USSD launch pad on your Unity dashboard.
  3. Select your preferred USSD Code and Sub Code from dropdowns.
  4. Select your rental period and provide a detailed description of your USSD Service (Purpose of the application).
  5. Click Pay Make We Go to confirm the details of the request. You will be directed to a confirmation page afterwards.
  6. Review the purchase order and confirm payment using your Hubtel credits.

USSD Code Request Approval

Kindly note that your requested code will be reviewed and approved (usually within 24hrs). After approval, you can then proceed to map your application URL to it and go live.

Map Your USSD Application

You need to map your application to an active code in order to receive live USSD sessions on your account. To map your application:

  1. Develop a USSD application in any programming language of choice and host on a live server.
  2. Login to your Hubtel account and navigate to your USSD dashboard.
  3. Click on Create an application and fill out the details.
  4. Ensure the application is Enabled.
  5. Map your application to any of the approved codes.

How the Hubtel USSD API Works

The Hubtel USSD API receives USSD requests from the mobile handset of a user via a Mobile Network Operator. The API then sends an HTTP POST request to your USSD service application URL for every USSD dial. The data sent to your app is a JSON payload. Your service application should be able to receive this request and parse the JSON data to perform your USSD service logic.

The diagram below depicts the flow for a USSD request:

Hubtel USSD API Request/Response Flow 
[*Click on image to enlarge*]

Hubtel USSD API Request/Response Flow
[Click on image to enlarge]

Hubtel has direct USSD connections to the following Mobile Network Operators:

  1. MTN Ghana
  2. Tigo Ghana
  3. Airtel Ghana
  4. Vodafone Ghana
  5. Glo Ghana
  6. Safaricom Kenya

Types of USSD Codes Available

  1. Dedicated USSD Code: The base code and all subcodes are dedicated to only one Unity account holder. Eg *737#. This is more expensive.
  2. Shared USSD Code: The subcodes of a code are shared by many Unity account holders Eg. 71420#. This makes it quite affordable for many businesses. Check the table below for details of the prices.
  3. Test USSD Code: These are shared USSD Codes which are available for test purposes. They are used to test your application in a live environment during development. These are codes with subcodes of more than 100000. Eg: 711100002# and 714100010#.

USSD Pricing

Ghana

Dedicated Service Code
Shared Service Code
Test Service Codes

Set Up Cost. Administrative and Regulatory(GHS)

5,000.00

0.00

0.00

Quarterly Rental Fee (3 months or 91 days)

7,500.00 per Network

600.00

75.00

USSD Transactions Per Session

An application is expected to respond to a USSD session within 7 seconds, otherwise, the session will time out. However, a user on the application can interact within the session for as long as it is allowed on the network.

The following represents the average number of USSD transactions per session for the various networks.

Network
Number of Transactions Per Session

Tigo

40

MTN

30

Airtel

30

Vodafone

20