HTTP API - HELP DOCUMENT

1. INTRODUCTION

This document is to provide help and illustrations to users 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 PARAMETER VALUE PARAMETER DESCRIPTION

NAME
1 USER TEST USER USERNAME OF THE ACCOUNT
2 PASSWD TEST PASSWORD PASSWORD OF THE ACCOUNT
3 SID SMSCOUNTRY (DEFAULT) SENDER ID
4 MOBILENUMBER MOBILE NUMBER DESTINATION MOBILE NUMBER
5 MESSAGE TEST MESSAGE 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 SMS SUBMITTED RETURN VALUE
9 MNO_MSG <MOBILE- MOBILE NUMBER AND
NUMBER1>^<MESSAGE1>~<MOBILE MESSAGE PATTERN FOR
NUMBER2>^<MESSAGE2> MULTIPLE SMS API

Table 2.1: Parameter Definitions

USERNAME: - USER
The user is free to choose his username at the time of registration. The user
parameter cannot be more than 17 characters long and can only contain alphabets
and numbers, with no blank spaces or special characters.

PASSWORD: - PASSWD
The user is free to choose his password at the time of registration. The
passwd 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:
 HTTP API - HELP DOCUMENT

The Sender id should be approved by SMSCountry.

You can have multiple sender id’s activated in your account.
You can send different API calls with different sender id’s provided that
the sender id is active for your account.
If an API call is made with a sender id that is not activated in user account
then SMS will be delivered by default or preferred sender id.
If user does not have a preferred sender id then by default “SMSCntry”
sender id will be delivered to end user handset.
You can change your preferred sender id in “My Account” page
by login 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 CHARACTER HEXA-DECIMAL ENCODED STRING

1 & %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 MTYPE DESCRIPTION

1 N NORMAL MESSAGE
2 OL UNICODE MESSAGE (EG: ARABIC, TELUGU, CHINESE, GREEK, ETC)
3 P PICTURE MESSAGE
4 L LOGO
5 F FLASH MESSAGE
6 WP WAPPUSH (SPECIFY THE WAP URL IN THE PARAMETER
WAP_URL)
7 LS LONG SMS (GPRS BASED)
8 R RINGTONE

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 User and Passwd (as described in the
Table 2.1: Parameter Definitions) for authentication purpose in below URL format

http://api.smscountry.com/SMSCwebservice_bulk.aspx?User=xxxxxx&passwd=xxxxxxxxxxx
x&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=xxxxxxxx
xx&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?User=xxxxxx&passwd=xxxxxxxxx&mobil
enumber=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?User=xxxxxx&passwd=x
xxxxxxxx&mno_msg=xxxxxxx^yyyyyyyy~xxxxxxx^yyyyyyy&sid=xx
xxxxxx&mtype=N&DR=Y

4 REPORTS

4.1 Customer Status Report

Each user can check his / her account status (Credits Purchased, Credits Available,
etc.) online by login into SMScountry account using the user name and password

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?user=xxxx&pass
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 –

SL. No STATUS RESPONSE

1 SMS MESSAGE SENT A) SMS MESSAGE SENT (IF DR=N)
B) UNIQUE NUMBER (IF DR=Y)
2 SMS MESSAGE NOT SENT A) INVALID USERNAME
B) YOUR ACCOUNT NOT ACTIVATED.
PLEASE CONTACT WEBMASTER.
C) INVALID PASSWORD
D) INVALID DATA
E) INSUFFICIENT BALANCE. PLEASE BUY
SMS TO SEND SMS
F) INVALID MOBILE NUMBER
G) SMS MESSAGE(S) NOT SENT
H) MOBILE NUMBER HAS OPTED NOT TO
RECEIVE ANY SMS
3 DELIVERY REPORT RECEIVED MOBILE NUMBER-STATUS-TIMESTAMP
SUCCESSFULLY 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
4 DELIVERY REPORT NOT A) INVALID USERNAME
RECEIVED B) INVALID PASSWORD

Table 4.1: Delivery Response & Status

 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_User_GetBal.asp?User=xxx&passwd=xx

The table below describes the response from the gateway –

S. NO STATUS RESPONSE
1 SMS BALANCE RECEIVED SUCCESSFULLY NUMBER
2 SMS BALANCE NOT RECEIVED SUCCESSFULLY A) INVALID USERNAME
B) INVALID PASSWORD

Table 5.1: Balance Check Responses

6 UNICODE MESSAGE

6.1 SMS containing normal text message http://api.smscountry.com/SMSCwebservice_bulk.aspx?

User=wworks&passwd=5hdshj3&mobilenumber=9198xxxxxx,97194xxxxxxxx&message=testin
gsmscountry&sid=wworks&mtype=N

6.2 SMS containing Unicode message (UCS-2)

This is basically used to support 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?User=wworks&passwd=5hdshj
3&mobilenumber=85298xxxxx&message=062A06450020062A0
633062C064A06440643002006280646062C0627062D00200641064A0020062E062F064506 290
0200631063306270626064400200627064406470627062A064100&Mtype=OL

6.3 SMS containing 8-bit binary data (e.g. for Ring tone/Logo)
http://api.smscountry.com/SMSCwebservice_bulk.aspx?User=wworks&passwd=5hdshj
3&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?
user=xxxxx&passwd=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
CONTACT DETAILS

For any queries or clarifications, please feel free to reach our support team at –

SMSCountry Networks Private Limited

Email: [email protected]