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.

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.

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.

The diagram below depicts the flow for a USSD request:

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

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.


Number of Transactions Per Session









Try This API

Updated 10 months ago

Getting started with USSD

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.