Sms Country Http Api 3gl4g

HTTP API - HELP DOCUMENT 1. INTRODUCTION This document is to provide help and illustrations to s who wish to delivery SMS using the SMSCountry SMS Gateway via the HTTP Protocol. Accessing gateway through HTTP API is one of the best and the quickest ways to deliver SMS messages. The HTTP API can be used to send various types of SMS messages including normal text messages, Unicode messages, ring tones, logos and picture messages.

This document gives a detailed explanation of using the gateway through HTTP API.

2. PARAMETER DEFINITION

The following table gives the list of parameters required for sending message through SMSCountry’s Gateway using the HTTP API.

S.NO

PARAMETER NAME

PARAMETER VALUE

PARAMETER DESCRIPTION

1



Test

2

wd

Test

name of the of the

3

Sid

SMSCountry(default)

Sender –id

4

Mobilenumber

Mobile Number

5

Message

Test Message

Destination Mobile Number Message to be sent

6

Mtype

N/OL/R/P/L/F/WP/LS

Type of message

7

DR

Y/N

Delivery report required

8

SMS_Job_NO

Message Id

9

mno_msg

Table 2.1: Parameter Definitions

SMS Submitted Return value <mobileMobile Number and number1>^<message1>~<mobile- message pattern for number2>^<message2> multiple sms API

HTTP API - HELP DOCUMENT NAME: - The is free to choose his name at the time of registration. The parameter cannot be more than 17 characters long and can only contain alphabets and numbers, with no blank spaces or special characters. : - WD The is free to choose his at the time of registration. The wd parameter cannot be more than 20 characters long and can only contain alphabets and numbers, with no blank spaces or special characters. SENDER-ID / NAME OF SENDER: - SID The Sender-Id refers to the Alphanumeric Identity of the Sender. For India an alphanumeric sender-id (of maximum 8 characters) is accepted. International SMS can have alphanumeric sender-id (of maximum 11 characters). Please Note:   The Sender-Id should be approved by SMSCountry.    You can have multiple sender Ids activated in your .   You can send different API calls with different sender ids provided that the sender id is active for your .    If an API call is made with a sender id not activated in then  by default his “preferred” sender id will be delive red.  If does not have a preferred sender id then by default “SMSCntry” will be delivered at end mobile.    You can change your preferred sender id in “My Acco unt” page by to http://www.smscountry.com  MOBILE NUMBER: - MOBILENUMBER This parameter refers to the destination mobile number(s) to which the message is to be sent. It must include the country code appended before the mobile number (eg: 9198xxxxxxx, 4478xxxxxxxx, 6591xxxxx). Any error in this parameter value would lead to non-delivery of the message. The mobile number should contain only numbers and no symbols like "+", “-“ etc.

MESSAGE: - MSG The msg parameter refers to the actual message that is to be sent to the destination mobile number. The format of the message differs depending on the type of message being sent. For simple text messages, the message can contain numbers, alphabets, spaces and certain special characters. The message can contain a maximum of 160 characters, including spaces.

In case of Unicode messaging, the message can contain only numbers in the form of Unicode digits. Further, it can have a maximum of 70 characters i.e. 70 x 4 Unicode digits for each character that means 280 digits. In case of binary messaging, the message can contain only valid 8-bit data string. The binary message can be a maximum of 140 characters only for each SMS. However, Ring tones, Logos and Pictures that exceed 140 characters can be sent as two / three SMS messages.

HTTP API - HELP DOCUMENT Due to restrictions in the HTTP protocol, the following special characters must be encoded, as shown below, to avoid collision with reserved HTTP characters –

S.NO 1

CHARACTER &

HEXA-DECIMAL ENCODED STRING %26

2

+

%2B

3

%

%25

4

#

%23

5 = %3D 6 ^ %5E 7 ~ %7E Table 2.2: Special Character Hexa Decimal Encodings MESSAGE TYPE: - MTYPE Message Type is to identify the type of message being sent. The default value of message type is N, which refers to Normal text message. SMSCountry’s Gateway classifies the type of messages to be sent on the basis of this parameter and pushes them accordingly.

S.NO 1

MTYPE N

DESCRIPTION Normal Text Message

2

OL

Unicode Message(eg: Arabic, Chinese, Greek , etc)

3

P

Picture Message

4

L

LOGO

5

F

Flash

6

WP

WapPush ( specify the Wap URL in the parameter WAP_URL ) Long SMS (GPRS based) Ringtone

7 LS 8 R Table 2.3: Message Type Description

HTTP API - HELP DOCUMENT 3. MESSAGING 3.1 Sending a Single Message To send a single message of any type (normal text messages, Unicode messages, ring tones, logos and picture messages), the gateway requires parameters like and wd (as described in the Table 2.1: Parameter Definitions) for authentication purpose in below URL format http://api.smscountry.com/SMSCwebservice_bulk.aspx? =xxxxxx&wd=xxxxxxxxxxxx&mobilenumber=xxxxxxxxxx&message=xxxxxxxxx&sid =xxxxxxxx&mtype=N&DR=Y

An Optional IP validation feature is also available for security of clients who access the gateway via a Global Static IP. http://api.smscountry.com/SMSCwebservice_bulk.aspx? mobilenumber=xxxxxxxxxx&message=xxxxxxxxx&sid=xxxxxxxx&mtype=N&DR=Y

3.2 Bulk Messaging For sending Bulk SMS messages, the following URL, along with the required parameters, needs to be accessed – http://api.smscountry.com/SMSCwebservice_bulk.aspx? =xxxxxx&wd=xxxxxxxxx&mobilenumber=xxxxxxx,xxxxxxx,xxxxxxxxx&message=xx xxxxxxx&sid=xxxxxxxx&mtype=N&DR=Y

3.3 Sending Multiple Messages to Multiple Mobile numbers (Customized SMS) For sending different messages to different mobile numbers in a single call, please use below URL along with required parameters:http://api.smscountry.com/SMSCWebservice_MultiMessages.asp? =xxxxxx&wd=xxxxxxxxx&mno_msg=xxxxxxx^yyyyyyyy~xxxxxxx^yyyyyyy&sid=xx xxxxxx&mtype=N&DR=Y

4 REPORTS 4.1 Customer Status Report Each can check his / her status (Credits Purchased, Credits Available, etc.) online by into SMScountry using the name and

4.2 Delivery Reports 4.2.1 Accessing Delivery Report with Time Duration For accessing delivery report for SMS messages sent during a particular date and time duration, the following URL, along with the required parameters, needs to be accessed – http://api.smscountry.com/smscwebservices_bulk_reports.aspx? =xxxx&wd=xxxx&fromdate=DD/MM/YYYY 00:00:00 &todate=DD/MM/YYYY 23:59:59 Response: - jobid~mobilenumber~messagestatus~donestamp~message_text~receivestamp# Sample Response: - 123456~919985111111~2~1/1/2008 11:30PM~test sms~1/1/2008 11:29PM

HTTP API - HELP DOCUMENT 4.2.2 Receiving Dynamic Delivery Report We also provide you Dynamic Delivery Reports with Call Back Script Option enabled. With this option, we will send Deliver Reports directly to the URL specified by you.

To get auto delivery response push at your end you need to provide us a URL that shall read below parameters from query string.  



 

 

jobno (ex:- xxxxxx) , mobilenumber (ex:- 91923XXXXXXX)  status (ex:- integer value, please refer API doc for status details  doneTime (ex:-format MM/DD/YYYY HH:MM:SS AM/PM)  messagepart (ex:- sms message sent by you) 

The table below describes the various types of response from the gateway –

S.NO STATUS 1 SMS message(s) sent 2

SMS message(s) not sent

3

Delivery Report Received Successfully

4

Delivery Report not Received

Table 4.1: Delivery Response & Status

RESPONSE

a)SMS message(s) sent (If DR=N) b) Unique Number (If DR=Y) a) Invalid Name!! b) Your not activated. Please !! c) Invalid !! d) Invalid Data e) Insufficient Balance!!! Please Buy SMS Credits f) Invalid mobile number(s) given g)SMS message(s) not sent h)Mobile number has opted not to receive any sms a) Mobile_Number-Status-TimeStamp Description for Status_ 0-Message In Queue 1 - Submitted To Carrier 2 - Un Delivered 3 – Delivered 4 – Expired 8 – Rejected 9 – Message Sent 10 – Opted Out Mobile Number 11 – Invalid Mobile Number a) Invalid Name!! b) Invalid !!

HTTP API - HELP DOCUMENT 5 SMS CREDIT BALANCE For getting SMS credit balance, the following URL, along with the required parameters, needs to be accessed – http://api.smscountry.com/SMSCwebservice__GetBal.asp?=xxx&wd=xx The table below describes the response from the gateway – S.NO 1

STATUS RESPONSE SMS Balance Received a) Number Successfully 2 SMS Balance Not Received a) Invalid Name!! Successfully b) Invalid !! Table 5.1: Balance Check Responses

6.1 SMS containing normal text message http://api.smscountry.com/SMSCwebservice_bulk.aspx? =wworks&wd=5hdshj3&mobilenumber=9198xxxxxx,97194xxxxxxxx&message=testin

gsmscountry&sid=wworks&mtype=N

6.2 SMS containing Unicode message (UCS-2) This is basically used to languages with characters not included in default GSM 7-bit character set . Find below an illustration url for sending a message in Arabic http://api.smscountry.com/SMSCwebservice_bulk.aspx? =wworks&wd=5hdshj3&mobilenumber=85298xxxxx&message=062A06450020062A0 633062C064A06440643002006280646062C0627062D00200641064A0020062E062F064506290 0200631063306270626064400200627064406470627062A064100&Mtype=OL

6.3 SMS containing 8-bit binary data (e.g. for Ring tone/Logo) http://api.smscountry.com/SMSCwebservice_bulk.aspx? =wworks&wd=5hdshj3&mobilenumber=44983xxxxxx&binmess= %06%05%04%15%81%00%00&message=%02J%3Ai%1D%BD%B1%91%19%A5%B9%9D %95%C8%04%00%25%18%C5%12a%06%19av %10%81%98%11%81%16%12%81&sid=wworks&mtype=R 6.4 SMS Containing multiple messages to multiple mobile numbers http://api.smscountry.com/SMSCWebservice_MultiMessages.asp? =xxxxx&wd=yyyyy&mno_msg=919xxxxxxx%5EHifirst message.%7E919xxxxxx %5Esencond sms message&DR=Y&mtype=N *The Mobile Number Prefixes seen in red

HTTP API - HELP DOCUMENT DETAILS For any queries or clarifications, please feel free to reach our team at SMSCountry Networks Private Limited # 407 & 408, Aditya Trade Center, Ameerpet, Hyderabad - 500038, Andhra Pradesh, India Telephone: 91-40-66505454 / 91-40- 66505999 Fax. : 91-40-4003-4403 (INDIA) Email: [email protected]

PDF to Word