Vodacom Developer Zone

SMS SMPP API 2.2.4 Specifications

August 23 2004
 SMPP API v. 2.2.4

CONTENTS
CONTENTS ........................................................................................................................................... 2
CHANGE HISTORY ............................................................................................................................... 3
OVERVIEW............................................................................................................................................ 3
SMPP API INTRODUCTION .................................................................................................................. 3
SUPPORTED PDUs............................................................................................................................... 3
AUTHENTICATION................................................................................................................................ 4
TON AND NPI ........................................................................................................................................ 4
ENQUIRE LINK...................................................................................................................................... 4
SMPP SPECIFICATIONS....................................................................................................................... 4
MOBILE ORGINATED ........................................................................................................................... 4
CONNECTION PROCEDURES.............................................................................................................. 6
APPLICATION PROCESS ............................................................................................................................. 6
COMPLIANCE TEST ................................................................................................................................... 6
ERROR CODES..................................................................................................................................... 7
MESSAGE STATUS .............................................................................................................................. 8
CONTACT DETAILS:............................................................................................................................. 9

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 2

 SMPP API v. 2.2.4

CHANGE HISTORY
Version Date Section Changes to Documentation
0.9 10 April 2003 Auth Corrected SMPP variable names
10 April 2003 Error Codes Added Hex Value
20 May 2003 PDUs Added deliver_sm, deliver_sm_resp
2.2.2 12 August 2003 Error Codes Revised Error Code Table
2.2.3 15 March 2004 Connection Added Requirements, Process. Tools
Procedures
2.2.4 23 August 2004 Mobile Added information on MO implementation
Originated

OVERVIEW
This document is intended for those users who wish to develop applications that make use of Vodazone’s
SMS Gateway. There are a number of different ways of gaining access to the Gateway:

• EMAIL to SMS - enabling a server or client generated email to be delivered as an SMS.

• HTTP / HTTPS - submitting either a POST or GET to the API server.
• FTP Upload – uploading a text file to Vodazone’s FTP Server.
• XML – Posting to Vodazone’s gateway using XML over HTTP
• COM Object – for Windows based development
• SMPP – Customers requiring a high throughput binary socket connection

We will cover the last method in this document. Additional documentation is available for the other
methods.

SMPP API INTRODUCTION

The Vodazone SMPP API offers an SMPP server connection using our standard auth system and error
codes. The error codes are available at the back of this document. To obtain a test account, you must
first register for a Vodazone account and a product on http://www.vodazone.co.za, fill out the IP lockdown
request form and submit the form to our support staff. We will then open up the firewall for that IP
address (please refer to Connection Procedures on page 5 of this document). We are currently SMPP
3.3 compliant although we allow bind_transceiver.

SUPPORTED PDUs
We support the following PDUs

Client to Server
bind_transmitter, bind_receiver, bind_transceiver. submit_sm, enquire_link, query_sm, deliver_sm_resp

Server to Client
bind_transmitter_resp, bind_receiver_resp, bind_transceiver_resp, submit_sm_resp, enquire_link_resp,
query_sm_resp, deliver_sm

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 3

 SMPP API v. 2.2.4

AUTHENTICATION
Your system_id and password are the same as your standard Vodazone Account username and
password.
You must set your system_type to be the sub_prod_id of your SMPP account.

§ system_id: account username

§ password: account password
§ system_type: numerical value, shown on the control page

TON AND NPI

DESTINATION ADDRESS
ton = 1
npi = 1

SOURCE ADDRESS
auto detected

Note: alphanumeric Sender ID is not available on all networks.

ENQUIRE LINK
Please set your enquire_link requests to 60 seconds.

SMPP SPECIFICATIONS
Visit www.smsforum.net for the SMPP 3.3 and SMPP 3.4 Specifications.

MOBILE ORGINATED
1) Enabling the ability to reply to MT messages

In order to ensure MT Messages can be replied to, the MT Message must be sent via a specific route,
which may be different from the usual route. If the System ID has a pre-configured number set up, then
Vodazone will automatically route the MT Message via this specified route. This has the same effect as
setting MO to 1/true in the other APIs.

2) Handling Inbound Messages (to the purchased MO number)

When we receive inbound messages from the handset - Vodazone will send the response to the client in
one of 3 ways (in addition to the online report):
• Callback URL (HTTP)
• FTP Logfile (FTP folder on Vodazone’s servers)
• SMPP (only for SMPP registered users)

If you have a keyword service Vodazone will send the destination address to you in this format:
number:keyword

Example: If you have a keyword CAT and an MO number 31000, then we will send the destination
address as 31000:cat to you.

If you do not have a keyword then we will just send the number to you without any additions.

a) Reply-path URL
The reply-path URL is set by Vodazone, and will be requested of the Client when MO is activated on their
account. The URL must begin with http://. Variables are passed back by the API on message response
The variables returned to the URL are:
Api_id (api_id=)
Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 4
 SMPP API v. 2.2.4

Originating ISDN (from=)

Destination ISDN (to=)
Date and Time [Unix time] (timestamp=)
DCS Character Coding (dcs=) [when applicable]
Header Data [e.g. UDH etc.] (udh=) [when applicable]
Message Data (text=)

Please note that for specific requests these fields can be changed.

b) Responses to an FTP log file

Replies can be logged to an FTP file. The FTP file will be a text file, which can be retrieved manually, or
via a script. To use this option please register for Vodazone’s FTP product and then use the provided
ftp_id for this.

This is a typical entry in this text file:

2004-09-27 10:51:14 27821234567 27825678901 Testing MO service.

The fields displayed are:

Message Data
Message Time
Originating ISDN
Destination ISDN (your MO number)
Message Data

c) Response via SMPP (for advanced users)

We can also send the response back to you via SMPP. Please see our website for more detail.

Important – please note that due to the fact that “mo” is not a feature supported by SMPP, we will route
all incoming messages on SMPP as if “mo=1” is specified. If a user has no MO numbers registered with
Vodazone, then they would not experience any difference. If a user has an MO number, then please
make sure you understand the affect of using MO and SMPP together.

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 5

 SMPP API v. 2.2.4

CONNECTION PROCEDURES

Minimum usage requirement: There is a monthly minimum of 5 000 credits that needs to be spent
in order to maintain a live SMPP account. At the end of the month you will be billed for any deficit
should this occur.

For example: You sent 3500 credits in a particular month. We will deduct a further 1500 credits at the end
of the monthly cycle to make up the shortfall. This may result in your account having a negative balance.

APPLICATION PROCESS

1) Apply for a new SMPP product (a valid e-mail address is required) via Vodazone Central or
http://www.vodazone.co.za/ (An automated response will be sent to you via e-mail). This will
register an account for you and send an application form to our support staff. In order for your
application to be successful, you will need a minimum of 5000 credits in your account and have
all fields in the form filled-in with legitimate information.
2) Your registration will be manually reviewed and you will be advised when Vodazone has
accepted your account for testing. If you have been approved an e-mail will be sent to the e-mail
address registered above. Note: Unfortunately no free-mail addresses such as @yahoo.com
and @hotmail.com, etc., are allowed.
3) Once your test account is live, you will be given access on the Vodazone firewall to
smpp.test.vodazone.co.za. The test server will allow you to send one SMS every two seconds.
Fake prefixes, to allow for end-to-end testing, will be offered at 1/3 of a credit for every message
response.
4) The test period is valid for one month (after three weeks, an automated e-mail will notify you that
you have one week left for testing, and would need to arrange for a compliance test) before being
moved to the production servers. At any stage, you may contact smpp (@) vodazone.co.za to
arrange a compliance test. A further e-mail will be sent 24 hours before any connection
termination, requesting an immediate response, or risk termination, as per Vodazone’s general
procedures.
5) If you pass the compliance test, a commercial SMPP account is configured on the production
server, and you will be required to migrate your commercial traffic onto the appropriate servers.
6) Dedicated throughput and throttling, at 5msg per second, will be available on the live SMPP
server.

COMPLIANCE T EST

The following conditions will be tested in the compliance test before we will issue you with a live SMPP
account.

1. Remain bound for 24 hours, unless our server is restarted.

2. Ensure that you only attempt one bind for transmitter/receiver or transceiver.
3. When we disconnect either a transmitter/receiver, you rebind automatically.
4. Your enquire_link interval is set to 60 secs.
5. Your submit_sm PDUs are correctly formatted.
6. You must be able to handle deliver_sm PDUs
7. When we send a deliver_sm, we get a deliver_sm response.

We actively monitor each SMPP connection. If there are any non-critical errors, we will contact you to
remedy these within 1 working day. Failure to do so will result in the account being moved back to
testing.

Any critical malfunctioning ESME’s that are affecting Vodazone’s service levels and SMPP server stability
will be communicated to you, and the account will be terminated immediately.

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 6

 SMPP API v. 2.2.4

ERROR CODES
The following list of error messages are generated by the Vodazone Gateway. There will be no message
charge if these errors are generated when sending a message.

SMPP Error Code Hex Value Description

SMPP_ESME_ROK 0x00000000 No Error
SMPP_ESME_RINVMSGLEN 0x00000001 Message Length is invalid
SMPP_ESME_RINVCMDLEN 0x00000002 Command Length is invalid
SMPP_ESME_RINVCMDID 0x00000003 Invalid Command ID
SMPP_ESME_RINVBNDSTS 0x00000004 Incorrect BIND Status for a given command
SMPP_ESME_RALYNBD 0x00000005 ESME Already in Bound State
SMPP_ESME_RINVREGDLVFLG 0x00000007 Invalid Registered Delivery Flag
SMPP_ESME_RSYSERR 0x00000008 System Error
SMPP_ESME_RINVSRCADR 0x0000000A Invalid Source Address
SMPP_ESME_RINVDSTADR 0x0000000B Invalid Destination Address
SMPP_ESME_RINVMSGID 0x0000000C Message ID is invalid
SMPP_ESME_RBINDFAIL 0x0000000D Bind Failed
SMPP_ESME_RINVPASWD 0x0000000E Invalid Password
SMPP_ESME_RINVSYSID 0x0000000F Invalid System ID
SMPP_ESME_RMSGQFUL 0x00000014 Message Queue Full
SMPP_ESME_RINVESMCLASS 0x00000043 Invalid esm_class field data
SMPP_ESME_RINVSRCTON 0x00000048 Invalid Source address TON
SMPP_ESME_RINVSYSTYP 0x00000053 Invalid system_type field
SMPP_ESME_RTHROTTLED 0x00000058 Throttling error
(ESME has exceeded allowed message
limits)
SMPP_ESME_RINVSCHED 0x00000061 Invalid Scheduled Delivery Time
SMPP_ESME_RINVEXPIRY 0x00000062 Invalid message validity period (Expiry Time)
SMPP_ESME_RX_T_APPN 0x00000064 ESME Receiver Temporary APP Error Code
SMPP_ESME_RX_P_APPN 0x00000065 ESME Receiver Permanent APP Error Code
SMPP_ESME_RX_R_APPN 0x00000066 ESME Receiver Reject Message Error Code
SMPP_ESME_ROPTPARNOTALL 0x000000C1 Optional Parameter not allowed
WD
SMPP_ESME_RINVPARLEN 0x000000C2 Invalid Parameter Length
SMPP_ESME_RUNKNOWNERR 0x000000FF Unknown Error
SMPP_ESME_ROUTERR 0x00000400 Cannot route message *
SMPP_ESME_NOCR 0x00000401 Out of credit
SMPP_ESME_MAXCR 0x00000402 Max Credit Exceeded
SMPP_ESME_ACCFROZ 0x00000403 Account Frozen
SMPP_ESME_DATAERR 0x00000404 Bad Data
SMPP_ESME_GENERR 0x00000405 ESME Client Error

Cannot route message *

This implies that the Vodazone Gateway is not currently routing messages to this network prefix. Please
e-mail [email protected] with the number in question.

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 7

 SMPP API v. 2.2.4

MESSAGE STATUS

Number Hex Description Detail

The delivering network did not recognise the
001 0x001 Message unknown
message type or content.
The message could not be delivered and has
002 0x002 Message queued
been queued for attempted redelivery.
Delivered to the network or gateway (delivered
003 0x003 Delivered
to the recipient).
Confirmation of receipt on the handset of the
004 0x004 Received by recipient
recipient
There was an error with the message,
005 0x005 Error with message probably caused by the content of the
message itself.
Client cancelled the message by setting the
User cancelled message
006 0x006 validity period, or the message was terminated
delivery
by an internal mechanism.
An error occurred delivering the message to
007 0x007 Error delivering message
the handset.
008 0x008 OK Message received by gateway.
The routing gateway or network has had an
009 0x009 Routing error
error routing the message.
Message has expired at the network due to
010 0x00A Message expired
the handset being off, or out of reach.
Message has been queued at the Vodazone
Message queued for later
011 0x00B gateway for delivery at a later time (delayed
delivery
delivery).
The message cannot be delivered due to a
012 0x00C Out of credit lack of funds in your account. Please re-
purchase credits.

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 8

 SMPP API v. 2.2.4

CONTACT DETAILS:

Phone: +27 21 948 7150

Fax: +27 21 948 7160
Web site: www.vodazone.co.za
E-Mail: [email protected]
[email protected]
[email protected]

Powered by Clickatell. Copyright © 2004 Clickatell (Pty) Ltd 9