NI USSD (USSD Push)

API
V1.6

www.alwaysactivemobile.co.za
care@aat.co.za
(+27) 031 100 0201
Contents
Version history ............................................................................................................................................................................ 3
Introduction................................................................................................................................................................................ 4
Availability .................................................................................................................................................................................. 4
NI USSD Functional Mechanism Overview ................................................................................................................................... 4
Internals of the NI USSD Daemon ............................................................................................................................................ 4
Initiate a NI USSD Session............................................................................................................................................................ 5
Query String Parameters ......................................................................................................................................................... 5
MSISDN .............................................................................................................................................................................. 5
Message ............................................................................................................................................................................. 5
Username ........................................................................................................................................................................... 5
Password ............................................................................................................................................................................ 5
ID ....................................................................................................................................................................................... 5
Server Response...................................................................................................................................................................... 5
Parameters ............................................................................................................................................................................. 5
Receiving Responses ................................................................................................................................................................... 6
Parameters ............................................................................................................................................................................. 6
NI USSD Timeouts and Character Limitations ............................................................................................................................... 7
MT (Mobile Terminating) Traffic .............................................................................................................................................. 7
MO (Mobile Originating) Traffic ............................................................................................................................................... 7
Network Session Timeouts ...................................................................................................................................................... 7
Handset Timeouts ................................................................................................................................................................... 7
Application Timeouts .............................................................................................................................................................. 7
Error Codes ................................................................................................................................................................................. 8
Integration................................................................................................................................................................................ 11
External Links ............................................................................................................................................................................ 11
Support..................................................................................................................................................................................... 11

2
Version history

Revision number Revision Date Author Changes

1.0 2013-12-17 Richard de Oude Initial document release
1.1 2014-01-27 Jon Hudson Updated Text
1.2 2014-02-03 Jon Hudson Updated URL
1.3 2014-03-24 Jon Hudson Updated HTTPS URL
1.4 2014-07-29 Jon Hudson Updated Text
1.5 2018-11-19 Jon Hudson Updated Timeouts
1.6 2019-05-16 Jon Hudson Updated MAP Codes (Network)

3
Introduction
NI USSD allows a USSD menu or simple notification to be pushed to a handset instead of the handset physically initiating the
session.

Our API described in the subsequent sections makes it simple for you to push a USSD session to all networks in South Africa.

Availability
NI USSD is only available to AAT Messaging Clients who are Financial Service Providers.

NI USSD Functional Mechanism Overview

This section of the doc is to explain in general how the NI USSD Daemon goes about handling USSD sessions. NI USSD
implementation centres around URL based requests and responses.

Upon creation of a new NI USSD campaign, the client is required to create the call-back URL for the NI USSD daemon. Later on in
this doc, examples of the XML and an example NI USSD session is given to aid in understanding of the system.

Internals of the NI USSD Daemon

Upon the NI USSD Daemon receiving the “USSD Push”, the daemon will initiate the USSD session and will deliver the specified
text to the handset. Any reply text or status change will be communicated back via an HTTP call. The client can continue the
session and send back further responses.

4
Initiate a NI USSD Session
To initiate a NI USSD session with the end user call:

https://ussdpush.gsm.co.za/push/

Query String Parameters

MSISDN
The end user MSISDN (international format e.g. 27821234567)

Message
The message to send

Username
Username Credentials

Password
Password Credentials

ID
A unique integer value.

Requesttype
Prompt :message is sent to the phone and it will prompt the user to reply
Notify :message is sent to the phone, with no reply needed.

Example:

https://ussdpush.gsm.co.za/push/?username=test&password=test&msisdn=27821231234&message=test%20message&id=12
345&requesttype=prompt

Server Response

<?xml version="1.0"?>
<result >
<description>… </ description >
<success>…</success>
<code>..</code>
<id>..</id>
</result>

Parameters

Success
If true the call succeeded, if false then the call was unsuccessful.

Description
Success was false, then this will contain an error message

Code
Error code

ID
Server transaction ID

5
Receiving Responses
Responses from the user will be delivered via HTTP to the URL specified in the configuration
The following values can be provided:

ID
The ID specified in the original push call

Message
The message sent from the handset

Network
Vodacom, MTN, CellC or Telkom Mobile

IMSI
If available

Type
Response, Release (session ended), Timeout (session timed out).
Timeout and release are not always provided by the network, so will only be sent if available.

Please provide the URL template in this format:

http://..URL..?id=#id#&imsi=#imsi#&network=#network#&message=#message#&type=#type

The parameter names etc can be anything, the system simply replaces the tokens.

The page must return the following xml

<?xml version=""1.0"" encoding=""utf-8"" ?>

<response>
<type>…</type>
<text>…</text>
</response>"

Parameters

Type
Prompt : Send text back to the end user and prompt for a reply.
Notify : Send text back to the end user and end the session.
End : End the session.

Text
Text to send back to the end user.

6
NI USSD Timeouts and Character Limitations

MT (Mobile Terminating) Traffic

Networks Characters
All 160

MO (Mobile Originating) Traffic

Network Characters
All 160

Network Session Timeouts

The total amount of time allowed on a single NI USSD Session.

Network Seconds
Vodacom 40
MTN 240
CellC 180
Telkom Mobile (8ta) 300

Handset Timeouts
Response received from handset to network

Network Seconds
Vodacom 30
MTN 30
CellC 30
Telkom Mobile (8ta) 45

Application Timeouts
Response received from application to network

Network Seconds
All 10

*All figures inclusive of VAT

7
Error Codes
These MAP error codes are provided back from each MNO and passed onto you for reference.

Code Description Detail Network

0 Operation timed out No communication was received from the GSM Vodacom / CellC
network. Status of message sent is unknown. This might
be a temporary error/condition.
1 Unknown Subscriber The GSM network reports that the subscriber is not Vodacom / CellC
known to the network. This is a permanent condition.
9 Illegal Subscriber The GSM network reports that the subscriber is not Vodacom / CellC
allowed. This is a permanent condition.
10 Bearer Service Not Provisioned The GSM network reports that the bearer attempted Vodacom / CellC
(e.g. USSD) is not provisioned for the subscriber. This is
a permanent condition.
11 Teleservice Not Provisioned The GSM network reports that the bearer attempted Vodacom / CellC
(e.g. USSD) is not provisioned for the subscriber. This is
a permanent condition.
12 Illegal Equipment The GSM network reports that the subscriber Vodacom / CellC
equipment is not allowed. This is a permanent
condition.
13 Call Barred (Check RICA status) The GSM network reports that the subscriber is barred Vodacom / CellC
on the network. This is a permanent condition until the
subscriber can be unbarred by the operator.
16 Illegal Supplementary Service The GSM network reports that the supplementary Vodacom / CellC
Operation service is not allowed for the subscriber. This is a
permanent condition.
17 Supplementary Service Error The GSM network reports that supplementary service Vodacom / CellC
Status error. This might be a permanent condition.
18 Supplementary Service Not The GSM network reports that the supplementary Vodacom / CellC
Available service is not available. This is a permanent condition.
19 Supplementary Service The GSM network reports that the supplementary Vodacom / CellC
Subscription Violation service is not allowed for the subscriber. This is a
permanent condition.
20 Supplementary Service The GSM network reports that the supplementary Vodacom / CellC
Incompatibility service is not compatible. This is a permanent condition
until the subscriber can rectify his handset.
21 Facility Not Supported The GSM network reports that the service is not Vodacom / CellC
supported. This is a permanent condition.
27 Absent Subscriber The GSM network reports that the subscriber is not Vodacom / CellC
currently reachable. This is a temporary condition.
29 Short Term Denial The GSM network is denying the request based on Vodacom / CellC
internal policies (e.g. Rate limiting or congestion). This is
a temporary condition and can be retried over the short
term.
30 Long Term Denial The GSM network is denying the request based on Vodacom / CellC
internal policies (e.g. Rate limiting or congestion). This is
a temporary condition and can be retried over the long
term.
34 Switching System Failure An unknown error occurred in the core network during Vodacom / CellC
the transaction with the subscriber. This is a temporary
condition.

8
35 Data Missing Incorrect data values were sent to the GSM network. Vodacom / CellC
This is a permanent condition. Transaction should be
retried with different/corrected values.
36 Unexpected Data Value Incorrect data values were sent to the GSM network. Vodacom / CellC
This is a permanent condition. Transaction should be
retried with different/corrected values.
37 Registration Failure There was a registration failure of the subscriber during Vodacom / CellC
a handover procedure and the transaction could not be
completed. This is a temporary condition.
38 Negative PW-Check Returned in cases where a password validation is Vodacom / CellC
required for the supplementary service and the
password is not correct. This is a permanent condition.
43 Number of PW Attempts Returned in cases where too many password validation Vodacom / CellC
Violation attempts were made for the supplementary service and
the password is not correct. This is a permanent
condition.
71 Unknown Alphabet The specified GSM alphabet is not known to the switch. Vodacom / CellC
This is a permanent condition.
72 USSD Busy The GSM network reports that the subscriber is already Vodacom / CellC
busy on a USSD session. This is a temporary condition.
120 NBR SB Exceeded N/A Vodacom / CellC
121 Rejected by User Transaction was aborted by the User before it could be Vodacom / CellC
completed. Depending on the user, this may or may not
be a permanent condition.
122 Rejected by Network Transaction was aborted by the network. This is a Vodacom / CellC
permanent condition.
123 Deflection to Served Subscriber Response if the transaction was diverted by the network Vodacom / CellC
to a different subscriber.
124 Special Service Code Use of the service code is reserved by the network Vodacom / CellC
operator. This is a permanent condition.
125 Invalid Deflected to Number The diverted-to number does not exist on the network Vodacom / CellC
or is invalid. This is a permanent condition.
126 Max Number of Multiparty N/A Participants Exceeded Vodacom / CellC
127 Network Resources Not Available Congestion or routing failure. This is a short-term Vodacom / CellC
temporary condition.
2200 SUCCESS Success Telkom
2201 FAIL Unspecified internal failure Telkom
2202 CONFIG Could not get NIUSSD configuration Telkom
2210 USSD_ARG_ENCODE Failed to encode USSD-Arg Telkom
2211 USSD_ARG_SEND_BEGIN Failed to send TCAP BEGIN USSD-Arg Telkom
2212 USSD_ARG_SEND_CONT Failed to send TCAP CONTINUE USSD-Arg Telkom
2215 USSD_ERROR Received TCAP error while waiting for subscriber Telkom
response
2216 USSD_DHP_ERROR Received TCAP DHP after sending USSD-Arg to HLR (e.g. Telkom
TC_U_ABORT - subscriber abort)
2217 USSD_CHP_ERROR Received TCAP CHP after sending USSD-Arg to HLR Telkom
2218 USSD_TIMEOUT Timeout while waiting for subscriber response Telkom
2219 USSD_REL_FAIL Failed to release USSD transaction Telkom
2220 USSD_REL_SUCCESS Released USSD transaction Telkom
2221 REQ_TIMEOUT Got timeout/error waiting for next request Telkom
2222 TERMINATE_REQ Got a terminate request Telkom
2223 SVC_CONT_TIMEOUT Timeout while waiting for the next request Telkom
2224 SVC_TERM Received termination from services that initiated the Telkom
transaction (e.g. NAV)
2230 NIUSSD_RES_FAIL Failed to send niussd_res to requestor Telkom

9
2240 USSD_ERROR_ABSENT_SU Received TCAP error. Absent subscriber Telkom
2241 USSD_ERROR_SYS_FAILU Received TCAP error. System Failure Telkom
2242 USSD_ERROR_USSD_BUSY Received TCAP error. USSD session busy Telkom
2243 USSD_ERROR_ILLEGAL_S Received TCAP error. Illegal subscriber Telkom
12316 no description The session was aborted because of the application MTN
session timeout expired. (Pull)
12500 no description An unknown error occurred. MTN
12504 unexpectedDataValue The error is returned by the network when it receives a MTN
parameter with an unexpected value, without type
violation. This error is returned by the responder if it is
not able to deal with the contents of the USSD string.
(Push) (Pull)
12511 no description The transaction ID specified is not valid. (Push) (Pull) MTN
12514 no description No push agent has been configured for the application. MTN
(Push)
12515 no description Push functionality is not supported on this MTN
implementation. (Push)
12516 no description Push initialisation failed (Push) MTN
12520 no description Menu redirection failed (Pull) MTN
12521 no description MAP Abort (Pull) MTN
12528 no description The session was aborted because of an application MTN
timeout. (Pull)
12529 no description The session was aborted because of a NIM timeout. MTN
(Push) (Pull)
12530 no description The session was aborted because of an application MTN
timeout after session resumption. (Pull)
12531 no description The session was aborted because of a NIM timeout after MTN
session resumption. (Pull)
12550 unknownSub The error is returned for an unknown subscriber. (Push) MTN
12551 callBarred This error is returned if the subscriber is barred. (Push) MTN
12552 absentSub The error is returned when the subscriber is absent. MTN
(Push)
12553 systemFailure The error is returned for network element system MTN
failure. (Push)
12554 dataMissing The error is returned for USSD push data missing. (Push) MTN
12555 unknownAlphabet This error is returned by the MS or the network when MTN
the alphabet/language used for the USSD operation is
not known by the network or the MS. (Push)
12556 ussdBusy (Push) This error is returned if the MS is already on a USSD MTN
session. (Push)
12557 networkError This error is returned when network provider aborts. MTN
(Push)
12558 userAbort This error is returned when user aborts. (Push) MTN
12559 IllegalEquipment This error is returned when the network returns an MTN
illegal equipment error
12560 IllegalSubscriber This error is returned when the network returns an MTN
illegal subscriber error
12561 pushProblem General push problem (Push) MTN

10
Integration
NI USSD can be used for a multitude of purposes by a Financial Service Provider, including:

• Call Centre Authentication

• Internet Banking
• Debit Card / Credit Card protection
• Website Logins

External Links

USSD Wikipedia Link - http://en.wikipedia.org/wiki/Unstructured_Supplementary_Service_Data

Support
We’ve tried to put all the information we could in this Guide, but we are sure you’ll have some questions.

Please email care@aat.co.za if you have any questions.

11