voda smpp 2 2 4

Vodacom Developer Zone

SMS SMPP API 2.2.4 Specifications

August 23 2004

2

SMPP API v. 2.2.4

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

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

3

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

Procedures Added Requirements, Process. Tools

2.2.4 23 August 2004 Mobile Originated

Added information on MO implementation

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

http://www.vodazone.co.za

4

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=)

http://www.smsforum.net

5

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.

6

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 TEST

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.

http://www.vodazone.co.za/

mailto:@yahoo.com

mailto:@hotmail.com

7

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_ROPTPARNOTALLWD

0x000000C1 Optional Parameter not allowed

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.

mailto:[email protected]

8

SMPP API v. 2.2.4


MESSAGE STATUS Number Hex Description Detail

001 0x001 Message unknown The delivering network did not recognise the message type or content.

002 0x002 Message queued The message could not be delivered and has been queued for attempted redelivery.

003 0x003 Delivered Delivered to the network or gateway (delivered to the recipient).

004 0x004 Received by recipient Confirmation of receipt on the handset of the recipient

005 0x005 Error with message There was an error with the message, probably caused by the content of the message itself.

006 0x006 User cancelled message delivery

Client cancelled the message by setting the validity period, or the message was terminated by an internal mechanism.

007 0x007 Error delivering message An error occurred delivering the message to the handset.

008 0x008 OK Message received by gateway.

009 0x009 Routing error The routing gateway or network has had an error routing the message.

010 0x00A Message expired Message has expired at the network due to the handset being off, or out of reach.

011 0x00B Message queued for later delivery

Message has been queued at the Vodazone gateway for delivery at a later time (delayed delivery).

012 0x00C Out of credit The message cannot be delivered due to a lack of funds in your account. Please re-purchase credits.

9

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]

http://www.vodazone.co.za




voda smpp 2 2 4

Documents