SMS-Gateway HTTP Interface Release 1 · 2015-02-03 · SMS Gateway. There are a number of different ways of gaining access to the Gateway: HTTP submitting either a POST or GET to

SMS-Gateway HTTP Interface

Release 15

Net2SMSNetreg

copy All Copyrights are reserved 2001-2013

Net2sms HTTP API v 15

2 Copyright copy 2014 Net2sms

Descriptions Page No OVERVIEW 3 HTTP API INTRODUCTION 3 1 BASIC COMMANDS 4 2 MESSAGE PARAMETERS 5 3 ADDITIONAL COMMANDS 7 4 SMS MESSAGE EXAMPLES 18 APPENDIX A ERROR CODES 19 APPENDIX B MESSAGE STATUS 21



Overview This document is intended for those users who wish to develop applications that make use of Net2smsrsquos SMS Gateway There are a number of different ways of gaining access to the Gateway

HTTP submitting either a POST or GET to the API server XML ndash Posting to Net2smsrsquos gateway using XML over HTTP

We will cover the First method in this document Additional documentation will be available soon for the other methods Sample code is provided on the site

HTTP API INTRODUCTION

This is one of the simpler server-based forms of communication to the Net2sms API It can be used either in the form of a HTTP POST or as an URL (GET) We recommend POST for larger data transfer due to the size limitations of GET Communication to our API can be done either via HTTP on port 80 or HTTPS on port 443 All calls to the API must be URL-encoded



1 BASIC COMMANDS 11 SEND A MESSAGE To facilitate sending an SMS with a single command we have included the ability to post UserName and password variables in httpsend_utf8asp One can send to multiple destination addresses by delimiting the addresses with commas The basic parameters required are PhoneNumbers = SMSData = Unicode = and Sender= which refer to the destination address and content of the message language sender respectively In the examples displayed in this document we will only refer to these basic parameters Other parameters may be used to enable different features These are discussed in the follow section Each message returns a unique identifier in the form of an API Message ID This can be used to track and monitor any given message Command httpswwwnet2smsnetapihttpsend_utf8aspusername=xxxxamppassword=xxxxampphonenumbers=xxxxampsmsdata=xxxxampunicode=xxxxampsender=xxxx Response Message OK Status Number Response Message [Credit] ID msgid Or Response Message Err Error number Response Message



2 MESSAGE PARAMETERS There are a variety of messaging and SMS features supported by Net2sms which can be activated by including an array of additional parameters in the post These parameters include those in the table below Multiple parameters may be added to a single post Name Description username Your account Username password Your account password sender The sourcesender address smsdata The text content of the message phonenumbers The destination address May be refereed to as the MSISDN - an International

Number Without any lsquo00rsquo prefix or leading + symbol Unicode Language code SMSDateTime Optional Max 30 Date and Time Desired deferred delivery date and

Time SMSTest Optional Boolean (True or False) Indicates test mode SMSGateway Optional Max 1 Integer Routing specification SmsRef Optional Max 20 String Id Reference sent by the user

21 MESSAGE PARAMETERS IN DETAIL 22 DESTINATION ADDRESS (PHONE NUMBERS) SMS messages need to be sent in the standard international format with country code followed by number no leading zero to the number and no special characters such as ldquo+rdquo or spaces For example a number in the Saudi Arabia being 0505123456 will become 966505123456 Command httpswwwnet2smsnetapihttpsend_utf8aspusername=xxxxamppassword=xxxxampphonenumbers=xxxxampsmsdata=xxxxampunicode=xxxxampsender=xxxx 23 SOURCE ADDRESS (SENDER) This source address (Sender ID) can be either a valid international format number between 1 and 16 characters long or an eleven character alphanumeric string Note This service is not guaranteed across all telephone networks and may interfere with delivery to certain handsets Different lengths may be supported by different networks Command httpswwwnet2smsnetapihttpsend_utf8aspusername=xxxxamppassword=xxxxampphonenumbers=xxxxampsmsdata=xxxxampunicode=xxxxampsender=xxxx



24 UNICODE If this value is set to Unicode the text field must contain two-byte UTF-16 Unicode Each SMS can handle a maximum of 70 characters Each Unicode character must be hex-encoded More information is available at httpwwwunicodeorg Alternatively Net2sms provides Auto converter to convert Arabic text to Unicode within httpwwwnet2smsnet Simply set the parameter to Arabic Value Status Arabic Text will be Unicode and Delivered as two-byte Unicode English Delivers the text in English Charest Unicode Delivers the text as two-byte Unicode Command 1 Unicode Message httpswwwnet2smsnetapihttpsend_utf8aspusername=xxxxamppassword=xxxxampphonenumbers=xxxxampsmsdata=0627064406440647ampunicode=unicodeampsender=xxxx 2 Arabic Message httpswwwnet2smsnetapihttpsend_utf8aspusername=xxxxamppassword=xxxxampphonenumbers=xxxxampsmsdata=هللاampunicode=arabicampsender=xxxx 3 English Message httpswwwnet2smsnetapihttpsend_utf8aspusername=xxxxamppassword=xxxxampphonenumbers=xxxxampsmsdata=Testampunicode=englishampsender=xxxx 25 TEST Parameter (SMSTest) If the SMSTest parameter is set TRUE (or 1) the Gateway will process the message but not deliver it A result code will be returned This mode is useful for debugging the SMS request in your application 26 Delay Delivery (SMSDateTime) If you wish to schedule SMS messages to send at a later date and time you can used this parameter to indicate Delay delivery value The upper limit is 180 days or 259200 minutes This should be greater than 10 minutes for best effect In order to delay the delivery of an SMS message include the parameter SMSDateTime = Set this to a relative value of the number of minutes you wish the message to be delayed by Net2sms will store the message until the required timeframe has elapsed The maximum delay time is 259200 minutes or 180 days 27 Routing (SMSGateway) This optional parameter indicates the choice of the routing Leave blank or set to zero (0) for the automatic routing 28 Reference (SMSRef) This parameter allow to send an ID Reference The string will be saved inside the record of the sms sent



3 ADDITIONAL COMMANDS 31 Authenticate User This will authenticate a specific user Command httpswwwnet2smsnetapiauthenticateaspusername=xxxxamppassword=xxxx Response Authentication successful Or ERR Error number 32 QUERY BALANCE This will return the number of credits available on this particular account The account balance is returned as a floating point value Command httpswwwnet2smsnetapigetbalanceaspusername=xxxxamppassword=xxxx Response Credit = xx or ERR Error number 33 QUERY TRANSACTION STATUS This will return the status of a transaction Command httpswwwnet2smsnetapiquerytranaspusername=xxxxamppassword=xxxxamptranID=xxxxx Response StrTransactionID =xxxxx Status =xxxx SMSCounts =99 SMSSent =99 SMSError =99 or ERR Error number



34 QUERY SENDER ID This will return the sender if itrsquos defined in the system Command httpswwwnet2smsnetapiGetSenderaspusername=xxxxamppassword=xxxxampSender=xxxx Response Sender =xxxx is Defined or ERR Error number 34 QUERY SENDER ID This will return the sender if itrsquos defined in the system Command httpswwwnet2smsnetapiGetSenderIDaspusername=xxxxamppassword=xxxxampSender=xxxx Response Sender ID = xxxx or ERR Error number 35 QUERY ACCESS LEVEL This will return the Access level Command httpswwwnet2smsnetapiGetlevelaspusername=xxxxamppassword=xxxx Response Access_Level = xx Or ERR Error number



36 Add New User Register a new user Mandatory fields UserName alphanumeric Min of 4 char and max of 30 char FirstName alphanumeric max of 30 char LastName alphanumeric max of 30 char Email a valid email address (an activation email will be sent to this email) MobileNo a valid Saudi mobile number in the international format 9665xxxxxxxx 12 char long

(The password will be sent to this mobile) Optional Fields CompanyName alphanumeric max of 30 char Address alphanumeric max of 30 char City alphanumeric max of 30 char State alphanumeric max of 30 char ZipCode numeric max of 30 char Country alphanumeric max of 30 char Phone numeric max of 30 char Command httpswwwnet2smsnetapiAddAccountaspUserName=xxxxampFirstName=xxxxampLastName=xxxxampCompanyName=xxxxampAddress=xxxxampCity=xxxxampState=xxxxampZipCode=xxxxampCountry=xxxxampPhone=xxxxampMobileno=xxxxampemail=xxxx Response UserID=xxxx Or ERR Error number



37 QUERY User profile This will return the user profile in an XML format Command httpswwwnet2smsnetapiGetprofileaspusername=xxxxamppassword=xxxx Response ltxml version=10 encoding=UTF-8gt ltProfilegt

ltUserIDgtxxxxltUserIDgt ltFirstNamegtxxxxltFirstNamegt ltLastNamegtxxxxltLastNamegt ltEmailgtxxxxltEmailgt ltMobileNogtxxxxltMobileNogt ltCompanyNamegtxxxxltCompanyNamegt ltAddressgtxxxxltAddressgt ltCitygtxxxxltCitygt ltStategtxxxxltStategt ltZipCodegtxxxxltZipCodegt ltCountrygtxxxxltCountrygt ltPhonegtxxxxltPhonegt ltStatusgtxxxxltStatusgt ltvalidatedgtxxxxltvalidatedgt ltSMSBalancegtxxxxltSMSBalancegt ltAccBalancegtxxxxltAccBalancegt

ltProfilegt Or ERR Error number



38 Edit User profile Edit user profile Editable fields FirstName alphanumeric max of 30 char LastName alphanumeric max of 30 char Email a valid email address (the account will be deactivated and an activation email will be sent to this email for activation) CompanyName alphanumeric max of 30 char Address alphanumeric max of 30 char City alphanumeric max of 30 char State alphanumeric max of 30 char ZipCode numeric max of 30 char Country alphanumeric max of 30 char Phone numeric max of 30 char Command httpswwwnet2smsnetapiEditAccountaspUserName=xxxxamp password=xxxx ampFirstName=xxxxampLastName=xxxxampCompanyName=xxxxampAddress=xxxxampCity=xxxxampState=xxxxampZipCode=xxxxampCountry=xxxxampPhone=xxxxampemail=xxxx Response Edition successful Or ERR Error number 39 QUERY Groups This will return a list of all groups for specific user in an XML format Command httpswwwnet2smsnetapiGetGroupsaspusername=xxxxamppassword=xxxx Response ltxml version=10 encoding=UTF-8gt ltGroupsgt ltGroupIDgtxxxxltGroupIDgt ltGroupNamegtxxxxltGroupNamegt ltGroupsgt Or ERR Error number



310 QUERY Members This will return a list of all members for specific user and group in an XML format Command httpswwwnet2smsnetapiGetMembersaspusername=xxxxamppassword=xxxxampGroupID=xxxx Response ltxml version=10 encoding=UTF-8gt ltMembersgt

ltMemberIDgtxxxxltMemberIDgt ltMemberNamegtxxxxltMemberNamegt ltMemberMobilegtxxxxltMemberMobilegt

ltMembersgt Or ERR Error number 311 QUERY PhoneBook This will return a list of all groups amp members for specific user and in an XML format Command httpswwwnet2smsnetapiGetPhoneBookaspusername=xxxxamppassword=xxxx Response ltxml version=10 encoding=UTF-8gt ltPhoneBookgt

ltGroupgt ltGroupIDgtxxxxltGroupIDgt ltGroupNamegtxxxxltGroupNamegt ltMembergt


ltMembergt ltGroupgt

ltPhoneBookgt Or ERR Error number



312 Add New Group Add new Group Command httpswwwnet2smsnetapiaddgroupaspusername=xxxxamppassword=xxxxampgroupname=xxxx Response GroupID=xxxx Or ERR Error number 313 Delete Group Delete a Group Command httpswwwnet2smsnetapideletegroupaspusername=xxxxamppassword=xxxxampGroupID=xxxx Response Deletion successful Or ERR Error number 314 Edit Group Edit a Group Command httpswwwnet2smsnetapiEditgroupaspusername=xxxxamppassword=xxxxampGroupID=xxxxampGroupName Response Edition successful Or ERR Error number 315 Add a new member Add a new member to a group Command httpswwwnet2smsnetapiAddmemberaspusername=xxxxamppassword=xxxxampgroupid=xxxxampmembername=xxxxampMemberMobile=xxxx Response MemberID=xxxx Or ERR Error number



316 Delete a new member Delete a member from a group Command httpswwwnet2smsnetapiDeletememberaspusername=xxxxamppassword=xxxxampMemberID=xxxx Response Deletion successful Or ERR Error number 317 Edit a new member Edit a member Command httpswwwnet2smsnetapiEditmemberaspusername=xxxxamppassword=xxxxampMemberID=xxxxampMemberName=xxxxampMemberMobile=xxxx Response Edition successful Or ERR Error number 318 QUERY Senders This will return a list of all Senders for specific user in an XML format Command httpswwwnet2smsnetapiGetSendersaspusername=xxxxamppassword=xxxxampArrayList=0 Response ltxml version=10 encoding=UTF-8gt ltSendersgt ltSenderIDgtxxxxlt SenderIDgt lt SenderNamegtxxxxlt SenderNamegt lt SenderStatusgtxxxxlt SenderStatusgt ltSendersgt Or ERR Error number



319 Add New Sender Add a new Sender Command httpswwwnet2smsnetapiaddsenderaspusername=xxxxamppassword=xxxxampsendername=xxxx Response SenderID=xxxx Or ERR Error number 320 Approve Sender Approve Sender if the sender is a valid mobile and an activation code has been sent to the mobile number Command httpswwwnet2smsnetapiApproveSenderaspusername=xxxxamppassword=xxxxampSenderID=xxxxampActivationCode=xxxx Response Activation successful Or ERR Error number 321 QUERY User Messages This will return a list of all user messages in an XML format Command httpswwwnet2smsnetapigetmessagesaspusername=xxxxamppassword=xxxx Response ltxml version=10 encoding=UTF-8gt ltMessagesgt

ltMsgIDgtxxxxltMsgIDgt ltMsgShortDescgtxxxxltMsgShortDescgt ltMsgDescgtxxxxlt MsgDesc gt

ltMessagesgt Or ERR Error number



322 Add New Message Add new Message Command httpswwwnet2smsnetapiaddMessageaspusername=xxxxamppassword=xxxxampShortDesc=xxxxampLongDesc=xxxx Response MsgID=xxxx Or ERR Error number 323 Delete Message Delete a Message Command httpswwwnet2smsnetapideleteMessageaspusername=xxxxamppassword=xxxxampMsgID=xxxx Response Deletion successful Or ERR Error number 324 Edit Message Edit a Message Command httpswwwnet2smsnetapiEditMessageaspusername=xxxxamppassword=xxxxampMsgID=xxxxampShortDesc=xxxxampLongDesc=xxxx Response Edition successful Or ERR Error number



325 Recover Password This function is for password recovery if UserName is known Command https wwwnet2smsnetapisendpasswordaspusername=xxxx Response Password Sent to mobile and email on file (If the users has logged on before an email and SMS will be send) Response Password Sent to mobile on file (If the users has never logged on only SMS will be send) Or ERR Error number 326 Recover Password This function is for password recovery if email is known Command https wwwnet2smsnetapiEmailpasswordaspemail=xxxx Response Password Sent to mobile on file Or ERR Error number 327 Process iPhone In-App Purchase Order Command httpswwwnet2smsnetapiProcessInAppPurchaseaspusername=xxxxamppassword=xxxxampmerchant_order_id=xxxxampqty=xxxxampprice=xxxxampamount=xxxx Response Order processed successfully Or ERR Error number



328 Process Android In-App Purchase Order Command httpswwwnet2smsnetapiProcessInAppPurchaseAndroidaspusername=xxxxamppassword=xxxxampmerchant_order_id=xxxxampqty=xxxxampprice=xxxxampamount=xxxx Response Order processed successfully Or ERR Error number 329 Contact US This form to email web service to contact us Command httpswwwnet2smsnetapiSendEmailaspusername=xxxxamppassword=xxxxampEmail=xxxxampBody=xxxx Response ltOkgt ltMessagegtYour message was sent successfully ThanksltMessagegt ltOkgt Or ERR Error number



4 EXAMPLES Here are some example URLrsquos that demonstrate how to use the API All values in these examples should be replaced by your own values 41 SIMPLE SMS EXAMPLES Sendmsg Command including authentication and sender ID httpswwwnet2smsnetapihttpsend_utf8aspusername=demoamppassword=demoampphonenumbers=1234567890123ampsmsdata=initial+test+messageampsender=MEampunicode=english 42 DELAY DELIVERY EXAMPLES This is a delay delivery examples for 2 hours httpswwwnet2smsnetapihttpsend_utf8aspusername=demoamppassword=demoampphonenumbers=1234567890123ampsmsdata=initial+test+messageampsender=MEampunicode=englishampSMSDateTime=120



APPENDIX A ERROR CODES The following list of error messages are generated by the Net2sms Gateway There will be no message charge if these errors are generated when sending a message Number Description 010 Authentication failed Invalid Username Or Password 011 Authentication failed User Not Active 012 Authentication failed User Expired 020 Invalid Sender 030 Invalid Phone Numbers 040 Invalid Unicode parameter 045 Invalid SMSTest parameter 050 Credit Not Available



060 SMSData Not valid 070 Session Time Out 075 Invalid DateTime parameter 076 Maximum delay time exceeded 080 Database Error 090 Gateway Error 091 Invalid Gateway parameter 092 Gateway Is Down 095 Service Is Down 096 Invalid Transaction ID 097 Invalid Group ID 098 Group Addition failed Invalid Group Name 099 Authentication failed Error 100 Group Addition failed Group Name already exist 101 Group Deletion failed Invalid Group ID 102 Group Edit failed Invalid Group ID 103 Group Edit failed Invalid Group Name 104 Member addition failed Invalid Member Name 105 Member addition failed Invalid Mobile Number 106 Member addition failed Invalid Group ID 107 Member Addition failed Member Name already exist 108 Member Deletion failed Invalid Member ID 109 Member Edit failed Invalid Member ID 110 Member Edit failed Invalid Member Name 111 Member Edit failed Invalid Mobile Number 112 Sender addition failed Invalid Sender Name or Invalid character 113 Sender Addition failed Sender Name already exist 114 Sender addition failed This service is for accounts with valid invoice 115 Sender Activation failed Invalid Activation Code 116 Sender Activation failed Invalid Sender ID 117 Sender Addition failed Sender ID does not exist 118 Sender Addition failed Activation Code is not correct 119 Sender Addition failed Sender is not Pending activation 120 Registration failed invalid User name 121 Registration failed Username already exists 122 Registration failed invalid first name 123 Registration failed invalid last name 124 Registration failed invalid mobile no 125 Registration failed invalid email 126 Registration failed Mobile No already exists 127 Profile Edit failed invalid email 128 Message Deletion failed Invalid Message ID 129 Message addition failed Invalid Short Message 130 Message addition failed Invalid Long Message 131 Message addition failed Message already exist 132 Message Edit failed Invalid Short Message



133 Message Edit failed Invalid Message ID 134 Message Edit failed Invalid Message 135 Authentication failed Invalid UserName 136 Authentication failed Invalid Email 137 Order Processing failed Invalid Merchant order id 138 Order Processing failed Invalid Quantity 139 Order Processing failed Invalid Price 140 Order Processing failed Invalid Total Amount 141 Order Processing failed Merchant order id already exist 142 Order Processing failed Database Error 143 Order Processing failed Receipt Verification Failed 144 Email send failed invalid email 145 Email send failed invalid email body



APPENDIX B MESSAGE STATUS Number Description Detail 000 OK Message Has Been Sent

001 Message queued The message has been queued for attempted redelivery



Descriptions Page No OVERVIEW 3 HTTP API INTRODUCTION 3 1 BASIC COMMANDS 4 2 MESSAGE PARAMETERS 5 3 ADDITIONAL COMMANDS 7 4 SMS MESSAGE EXAMPLES 18 APPENDIX A ERROR CODES 19 APPENDIX B MESSAGE STATUS 21























































































































































































































































































































































































































































































































































































































































































































































































































































































































































Documents

SMS-Gateway HTTP Interface Release 1 · 2015-02-03 · SMS Gateway. There are a number of different ways of gaining access to the Gateway: HTTP submitting either a POST or GET to