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 0.9 Date 10 April 2003 10 April 2003 20 May 2003 12 August 2003 15 March 2004 23 August 2004 Section Auth Error Codes PDUs Error Codes Connection Procedures Mobile Originated Changes to Documentation Corrected SMPP variable names Added Hex Value Added deliver_sm, deliver_sm_resp Revised Error Code Table Added Requirements, Process. Tools Added information on MO implementation

2.2.2 2.2.3 2.2.4

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. 2. 3. 4. 5. 6. 7. Remain bound for 24 hours, unless our server is restarted. Ensure that you only attempt one bind for transmitter/receiver or transceiver. When we disconnect either a transmitter/receiver, you rebind automatically. Your enquire_link interval is set to 60 secs. Your submit_sm PDUs are correctly formatted. You must be able to handle deliver_sm PDUs 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 SMPP_ESME_ROK SMPP_ESME_RINVMSGLEN SMPP_ESME_RINVCMDLEN SMPP_ESME_RINVCMDID SMPP_ESME_RINVBNDSTS SMPP_ESME_RALYNBD SMPP_ESME_RINVREGDLVFLG SMPP_ESME_RSYSERR SMPP_ESME_RINVSRCADR SMPP_ESME_RINVDSTADR SMPP_ESME_RINVMSGID SMPP_ESME_RBINDFAIL SMPP_ESME_RINVPASWD SMPP_ESME_RINVSYSID SMPP_ESME_RMSGQFUL SMPP_ESME_RINVESMCLASS SMPP_ESME_RINVSRCTON SMPP_ESME_RINVSYSTYP SMPP_ESME_RTHROTTLED

Hex Value 0x00000000 0x00000001 0x00000002 0x00000003 0x00000004 0x00000005 0x00000007 0x00000008 0x0000000A 0x0000000B 0x0000000C 0x0000000D 0x0000000E 0x0000000F 0x00000014 0x00000043 0x00000048 0x00000053 0x00000058

SMPP_ESME_RINVSCHED SMPP_ESME_RINVEXPIRY SMPP_ESME_RX_T_APPN SMPP_ESME_RX_P_APPN SMPP_ESME_RX_R_APPN SMPP_ESME_ROPTPARNOTALL WD SMPP_ESME_RINVPARLEN SMPP_ESME_RUNKNOWNERR SMPP_ESME_ROUTERR SMPP_ESME_NOCR SMPP_ESME_MAXCR SMPP_ESME_ACCFROZ SMPP_ESME_DATAERR SMPP_ESME_GENERR

0x00000061 0x00000062 0x00000064 0x00000065 0x00000066 0x000000C1 0x000000C2 0x000000FF 0x00000400 0x00000401 0x00000402 0x00000403 0x00000404 0x00000405

Description No Error Message Length is invalid Command Length is invalid Invalid Command ID Incorrect BIND Status for a given command ESME Already in Bound State Invalid Registered Delivery Flag System Error Invalid Source Address Invalid Destination Address Message ID is invalid Bind Failed Invalid Password Invalid System ID Message Queue Full Invalid esm_class field data Invalid Source address TON Invalid system_type field Throttling error (ESME has exceeded allowed message limits) Invalid Scheduled Delivery Time Invalid message validity period (Expiry Time) ESME Receiver Temporary APP Error Code ESME Receiver Permanent APP Error Code ESME Receiver Reject Message Error Code Optional Parameter not allowed Invalid Parameter Length Unknown Error Cannot route message * Out of credit Max Credit Exceeded Account Frozen Bad Data ESME Client Error

Cannot route message * This implies that the Vodazone Gateway is not currently routing messages to this network prefix. Please e-mail support@vodazone.co.za with the number in question.

Powered by Clickatell.

Copyright © 2004 Clickatell (Pty) Ltd

7

SMPP API v. 2.2.4

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

006 007 008 009 010 011

0x006 0x007 0x008 0x009 0x00A 0x00B

012

0x00C

Powered by Clickatell.

Copyright © 2004 Clickatell (Pty) Ltd

8

SMPP API v. 2.2.4

CONTACT DETAILS:

Phone: Fax: Web site: E-Mail:

+27 21 948 7150 +27 21 948 7160 www.vodazone.co.za support@vodazone.co.za info@vodazone.co.za sales@vodazone.co.za

Powered by Clickatell.

Copyright © 2004 Clickatell (Pty) Ltd

9