SMS Gateway Center API Document

API Version 2.1

http://www.smsgatewaycenter.com

SMS GATEWAY CENTER API DOCUMENT

2014

2014 SMSGatewayCenter.com. A unit of Popular SoftTech and Marketing Pvt. Ltd.,

All rights reserved. No parts of this work may be reproduced in any form or by any means graphic, electronic, or mechanical, including photocopying, recording, taping, or information
storage and retrieval systems - without the written permission of the publisher. Products that
are referred to in this document may be either trademarks and/or registered trademarks of
the respective owners. The publisher and the author make no claim to these trademarks.
While every precaution has been taken in the preparation of this document, the publisher
and the author assume no responsibility for errors or omissions, or for damages resulting
from the use of information contained in this document or from the use of programs and
source code that may accompany it. In no event shall the publisher and the author be liable
for any loss of profit or any other commercial damage caused or alleged to have been
caused directly or indirectly by this document.

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

2|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

Contents
1.0 Getting Started ........................................................................................................................ 4
1.1 Prior Checklist .......................................................................................................................... 4
1.2 Full URL for Message Sending .................................................................................................. 4
1.3 SMS Message Encoding ............................................................................................................ 4
1.4 Default Parameters .................................................................................................................. 5
2.0 Send a Single SMS Message ..................................................................................................... 5
2.1 SMS Message Parameters ........................................................................................................ 5
2.2 Success Response .................................................................................................................... 6
2.3 Error Response ........................................................................................................................ 6
2.4 Examples ................................................................................................................................. 7
3.0 Send Multiple Mobile Messages............................................................................................... 8
4.0 Send Group SMS ...................................................................................................................... 8
5.0 Sample Codes .......................................................................................................................... 8
5.1 Sample PHP Code for sending SMS Message ............................................................................ 8
5.2 Sample JAVA Code for Sending SMS message........................................................................... 9
6.0 Miscellaneous ........................................................................................................................ 10
6.1 Delivery Report ...................................................................................................................... 10
6.2 Change Password................................................................................................................... 11
6.3 Check Balance ........................................................................................................................ 11
6.4 Miss Call Report ..................................................................................................................... 11
6.5 Short code Report .................................................................................................................. 11
6.6 Opt in Users Report ............................................................................................................... 11
6.7 Delivery Summary Report ...................................................................................................... 12

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

3|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

1.0 Getting Started

Our API resides at http://www.smsgatewaycenter.com/library/send_sms_2.php

1.1 Prior Checklist

You will have to prior things before using our API:
1. User and Password. If you are not an existing client, you can sign up at
http://www.smsgatewaycenter.com
2. URL encoding of certain parameters.

1.2 Full URL for Message Sending

http://www.smsgatewaycenter.com/library/send_sms_2.php?UserName=username&Password=pas
sword&Type=Bulk&To=91xxxxxxxxxx&Mask=YourSenderid&Message=
Hello%20Samir%2C%0APlease%20note%20our%20new%20number%0ARegards%0Ame%40me.com
Replace the parameters:
Username = Your Registered Username
Password = Your Registered Encoded Password
91xxxxxxxxxx = Your Recipients Mobile Number
YourSenderid = Your Approved Sender Name
Message = Your URL Encoded Message as
Hello%20Samir%2C%0APlease%20note%20our%20new%20number%0ARegards%0Ame%40me.com

Hello Samir,
Please note our new number
Regards
me@me.com

1.3 SMS Message Encoding

The SMS Message needs to be URLENCODED which is also known as PERCENT ENCODING string of
UTF-8 characters.
For more information on URL encoding, please see this: http://en.wikipedia.org/wiki/Percentencoding
Above highlighted message in yellow is actually URLEncoded.
Actual Message content is (Original Message content)

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

4|P a ge

2014

SMS GATEWAY CENTER API DOCUMENT

Encoded Text:
Hello%20Samir%2C%0APlease%20note%20our%20new%20number%0ARegards%0Ame%40me.com

1.4 Default Parameters

Parameter
UserName

Value
Account username provided by
SMS Gateway Center

Password

URL Encoding of UTF8

Characters

1.1

Details
Username should be
alphanumeric as assigned while
creating account.
The password must contain
same as you use to login to SMS
Gateway Center
Default Version is 1.1.
(optional)

2.0 Send a Single SMS Message

You have seen the basic parameters and how you must include basic parameters with URL Encoding.
Now, let us see how we can send a single SMS message using the API.
Currently SMS Gateway Center accepts plain text message with URL encoding.

2.1 SMS Message Parameters

Parameter
Type

Value
Individual, Bulk, Group

Language

English, Other

To

Mobile Number of the recipient

Mask

Sender Name approved by SMS

Gateway Center

Message

URL Encoded String of UTF-8

Characters

Duplication

on/off (optional)

Details
Indicates the type of message,
single, comma separated or
group message
Optional to include language
type, default is English.
This needs to be a pure
numeric format without any
special or alpha characters
6 Character sender name which
is approved by SMS Gateway
Center
The content which needs to be
sent and can contain alphanumeric with special characters
Default is on. This removes the
duplicate mobile numbers to
avoid sending multiple times.

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

5|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

2.2 Success Response

When Successful Request gets executed, then HTTP 200 Response will be generated. The response
to any SMS request is a string of tokens separated by pipe symbol (|).
A success response is
SUCCESS | Success (1) Fail (0) | Total Sms Cost (1)
This indicates that your request has been successfully submitted to operator. Success (1) Fail (0)
shows the number of mobiles included and Total Sms Cost (1) is basically SMS length message, if you
include more than 160 characters then it will show Total Sms Cost (2)

2.3 Error Response

An error response is generated when it fails to validate the required parameter while sending SMS
from API. It validates for all given parameters and some of them are listed below:
Username or password mismatch
error | 2115 | USERNAME OR PASSWORD IS INVALID
Type mismatch
error | 2116 | SMS SENDING TYPE IS UNKNOWN. PLEASE VERIFY.
Mobile Number mismatch
error | 2110 | PLEASE TYPE MOBILE NUMBER
Sender Name mismatch
error | 2107 | PLEASE ENTER THE SENDER ID
Empty Message content
error | 2108 | PLEASE TYPE YOUR MESSAGE
Operator downtime/unavailable
error | 2101 | SERVICE PROVIDER NOT AVAILABLE
Group Name mismatch
error | 2111 | PLEASE SELECT A GROUP
SMS Balance is 0
error | 2106 | NOT HAVING ENOUGH BALANCE TO SEND SMS
SMS Length Exceeded than assigned
error | 2119 | MAXIMUM SMS LENGTH EXCEEDED
User Account is blocked
error | 2113 | USER ACCOUNT HAS BEEN BLOCKED
User Account is expired
error | 2114 | USER ACCOUNT HAS BEEN EXPIRED
Gateway Closed
error | 999 | Gateway Closed
SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

6|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

error | 912 | Gateway Closed

If parameter is not supported via API
error | 2220 | NOT SUPPORT VIA API
Multiple parameters mismatched
error | 2116 | SMS SENDING TYPE IS UNKNOWN. PLEASE VERIFY.
Excel File Writing Error
error | 2105 | UNKNOWN ERROR
Maximum SMS in Excel File
error | 2121 | SYSTEM ONLY SUPPORT (5000 OR 30000 OR 100000) SMS AT A TIME
Schedule date mismatch
error | 2104 | SCHEDULED DATE IS INVALID
Sender name or mobile number mismatch
error | 2126 | MASK OR MOBILE NO OR SMS LENGTH IS NOT VALID

2.4 Examples
Find the below example with two sending SMS types. One is sending plain text message and other is
Unicode or other language SMS using API.
a) Plain English Text
http://www.smsgatewaycenter.com/library/send_sms_2.php?UserName=userxxxx&Password= passxxxx
&Type=Individual&To=9930447726&Mask=DEMO&Message=
Hello%20Neha%2C%0ACall%20me%20on%20my%20number.%20I%20am%20looking%20for%20SMS%20Gatewa
y%20in%20India.%0ARegards%0ASamir
Success Response: SUCCESS | Success (1) Fail (0) | Total Sms Cost (1)
Message Text on Recipients Mobile:
Hello Neha,
Call me on my number. I am looking for SMS Gateway in India.
Regards
Samir

b) Other Language
http://www.smsgatewaycenter.com/library/send_sms_2.php?UserName=userdemo&Password= userxxxx
&Type=Individual&Language=Other&To=9930447726&Mask=DEMO&Message=
%E0%A4%8F%E0%A4%B8%E0%A4%8F%E0%A4%AE%E0%A4%8F%E0%A4%B8%20%E0%A4%97%E0%A5%87%E0%
A4%9F%E0%A4%B5%E0%A5%87%20%E0%A4%B8%E0%A5%87%E0%A4%82%E0%A4%9F%E0%A4%B0
Success Response: SUCCESS | Success (1) Fail (0) | Total Sms Cost (1)
Message Text on Recipients Mobile:

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

7|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

3.0 Send Multiple Mobile Messages.

You can send SMS messages to multiple mobiles at once. Here is an example for sending Comma
Separated Mobile Numbers.
http://www.smsgatewaycenter.com/library/send_sms_2.php?UserName=userxxx&Password=passx
xxx&Type=Bulk&To=9930447726,9619141191,9769818858&Mask=DEMOSG&Message=
Hello%20World
Response: SUCCESS | Success (3) Fail (0) | Total Sms Cost (3)

4.0 Send Group SMS

You can send SMS to your created group on our web SMS panel. For example, on
www.smsgatewaycenter.com, you have created your group and added few contacts to that group
then you can send SMS to that respective group.
http://www.smsgatewaycenter.com/library/send_group_sms.php?UserName=userxxxx&Password=
passxxxx&Type=Group&Group=GroupName&Mask=Senderid&Duplication=on&Message=
Hello%20World
Response: SUCCESS | Success (10) Fail (0) | Total Sms Cost (10)

5.0 Sample Codes

5.1 Sample PHP Code for sending SMS Message
<?php
$sendsms =""; //initialise the sendsms variable
$param[To] = "919xxxxxxxxx";
$param[Message] = "Hello World";
$param[UserName] = "userxxxx";
$param[Password] = "passxxxx";
$param[Mask] = "DEMOSG";
$param[v] = "1.1"; //optional
$param[Type] = "Individual"; //Can be "Bulk/Group
//We need to URL encode the values
foreach($param as $key=>$val)
{
$sendsms.= $key."=".urlencode($val);
$sendsms.= "&"; //append the ampersand (&) sign after each parameter/value
}
$sendsms = substr($sendsms, 0, strlen($sendsms)-1);//remove last ampersand (&) sign from the sendsms
$url = "http://www.smsgatewaycenter.com/library/send_sms_2.php?".$sendsms;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$curl_scraped_page = curl_exec($ch);
curl_close($ch);
echo $curl_scraped_page;
?>

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

8|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

5.2 Sample JAVA Code for Sending SMS message

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.Date;
public class SMSGatewayCenterAPI {
public static void main(String[] args){
try {
Date mydate = new
Date(System.currentTimeMillis());
String data = "";
data += "Mask=DEMOSG";
data += "&UserName=userxxxx"; // your loginId
data += "&Password=" + URLEncoder.encode("passxxxx", "UTF-8"); // your password
data += "&Message=" + URLEncoder.encode("SMS Gateway Center message" +
mydate.toString(), "UTF-8");
data += "&To=" + URLEncoder.encode("9930447726", "UTF-8"); // a valid 10 digit phone no.
data += "&v=1.1" ;
data += "&Type=Individual"; // Can be "Bulk" or "Group"
URL url = new
URL("http://www.smsgatewaycenter.com/library/send_sms_2.php?" + data);
HttpURLConnection conn = (HttpURLConnection)url.openConnection();
conn.setRequestMethod("GET");
conn.setDoOutput(true);
conn.setDoInput(true);
conn.setUseCaches(false);
conn.connect();
BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String line;
StringBuffer buffer = new StringBuffer();
while ((line = rd.readLine()) != null){
buffer.append(line).append("\n");
}
System.out.println(buffer.toString());
rd.close();
conn.disconnect();
}
catch(Exception e){
e.printStackTrace();
}
}
}
SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

9|P a ge

SMS GATEWAY CENTER API DOCUMENT

2014

6.0 Miscellaneous
6.1 Delivery Report
http://www.smsgatewaycenter.com/library/deliveryreport.php?UserName=username&Password=p
assword&DateFrom=2014-11-10&DateTo=2014-11-11
Date Format: yyyy-mm-dd
Delivery report is given with two parameters for status remarks.
1. Status
2. Cause
You will get status as SUCCESS OR FAIL and in Cause column, you will get all cause remarks whether
delivered or failed cause as listed below.
List of Possible values for status and cause:
Status
SUCCESS
FAIL

SUBMITTED

Cause
SUCCESS
ABSENT SUBSCRIBER
UNKNOWN SUBSCRIBER
BLOCKED SENDERNAME
SYSTEM FAILURE
CALL BARRED
SERVICE DOWN
OTHER
DND FAIL
DND TIMEOUT
OUTSIDE WORKING HOUR
TIMEOUT

Cause Explanation:

ABSENT SUBSCRIBER: Operator could not reach the recipient.

UNKNOWN SUBSCRIBER: Unknown OR invalid number
BLOCKED SENDERNAME: Sender Name is blocked by SMS Gateway Center
SYSTEM FAILURE: Originating or Destination Operator system failure
CALL BARRED: Either operator or subscriber has blocked the number for unknown reasons.
SERVICE DOWN: Operator service is temporarily down.
OTHER: Message that are sent but could not be delivered for reasons that do not fall under
any mentioned category
DND FAIL: Mobile number is DND database or does not want to receive messages being
regular complaints.
DND TIMEOUT: Latest DND status is not available for the maximum 1 day time.
OUTSIDE WORKING HOUR: SMS Message sending is outside mentioned deliverable hours.
You can use the above URL and fetch the delivery report. Status gets updated every 2 hours for
Promotional SMS route and every 30 minutes for Transactional SMS route.

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

10 | P a g e

SMS GATEWAY CENTER API DOCUMENT

2014

6.2 Change Password

You can change password using API. URL is as follow:
http://www.smsgatewaycenter.com/library/change_password.php?Username=userxxxx&OldPassw
ord=passxxxx&NewPassword=newpassxxxx
Success Response: SUCCESS | PASSWORD HAS BEEN CHANGED SUCCESSFULLY
Failure Response: error | 2115 | USERNAME OR PASSWORD IS INVALID

6.3 Check Balance

You can check your SMS balance using our API, URL is as follow:
http://www.smsgatewaycenter.com/library/checkbalance.php?Username=userxxxx&Password=pass
xxxx
Success Response: Balance : 2041 | Expire Date : 2016-09-30
Failure Response: error | 2115 | USERNAME OR PASSWORD IS INVALID

6.4 Miss Call Report

You can fetch all reports by using this API.
http://www.smsgatewaycenter.com/library/miscall_report.php?UserName=userxxxx&Password=pa
ssxxxx&DateFrom=2014-11-10&DateTo=2014-11-11
Note: Date Format: yyyy-mm-dd

You will get timestamp, recipients mobile number, circle, operator values.

6.5 Short code Report

You can fetch all your short code report using our API.
http://www.smsgatewaycenter.com/library/shortcode_report.php?UserName=userxxxx&Password
=passxxxx&DateFrom=2014-11-10&DateTo=2014-11-11
Note: Date Format: yyyy-mm-dd

You will get timestamp, recipients mobile number, circle, operator values.

6.6 Opt in Users Report

You can fetch the opted recipients users list using our API.
http://www.smsgatewaycenter.com/library/optin_report.php?UserName=userxxxx&Password=pas
sxxxx&DateFrom=2014-11-10&DateTo=2014-11-11
Note: Date Format: yyyy-mm-dd

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

11 | P a g e

SMS GATEWAY CENTER API DOCUMENT

2014

You will get timestamp, recipients mobile number, circle, operator values.

6.7 Delivery Summary Report

Fetch daily SMS consumption summary using our API
http://www.smsgatewaycenter.com/library/delivery_summary_report.php?UserName=userxxxx&P
assword=passxxxx&DateFrom=2014-11-10&DateTo=2014-11-11
Note: Date Format: yyyy-mm-dd
You will get date, SMS consumed values.

Popular SoftTech and Marketing Pvt. Ltd.,

#225 & 226, Ground Floor, Raghuleela Mega Mall, Boraspada Road, Kandivali West, Mumbai
4000067
Phone: +91-22-28657726
Mobile: +919930 447 726
Fax: +91-22-67105508
Email: contact@smsgatewaycenter.com
Website: http://www.smsgatewaycenter.com

SMSGatewayCenter.com (A unit of Popular SoftTech and Marketing Pvt. Ltd.,)

12 | P a g e